Custom Domains

Custom Domains

Custom Domains let users route Bio pages, QR redirects, and Short URLs through their own domain. Customers should only configure DNS in their DNS provider. They should not need server, Nginx, Apache, or hosting panel access.

Key rule

DNS points a hostname to LinkQR. DNS does not point to a folder path. Use a hostname as the target, not a URL.

Correct target: youdomain.com
Wrong target: https://youdomain.com
Wrong target: youdomain.com/linkqr

App routing host

Show the app routing host clearly in the Custom Domains screen:

youdomain.com

Public paths such as /s/{code}, /q/{code}, and /b/{slug} are Laravel routes. They are not DNS values.

Customer DNS records

Root domain

For customer-domain.com:

Type: CNAME
Name: @
Target: youdomain.com
Proxy status: Proxied
TTL: Auto

Cloudflare supports root CNAME through CNAME flattening. Some DNS providers do not support root CNAME; in that case use A/AAAA records to the platform IP address or ask the customer to use a subdomain.

Subdomain

For links.customer-domain.com:

Type: CNAME
Name: links
Target: youdomain.com
Proxy status: Proxied
TTL: Auto

The customer can choose any hostname they control, such as links, go, qr, or a root domain. LinkQR should not force a fixed subdomain name.

TXT verification

Root domain: Name @, Content qr-verify-...
Subdomain: Name links, Content qr-verify-...

Use the exact verification token generated by LinkQR. DNS providers may display TXT values with quotes; verification should handle quoted TXT values.

Server requirement for SaaS

The LinkQR application server must accept unknown customer hostnames and route them to the same Laravel app. For Nginx, make the LinkQR site the default/catch-all server so customers do not require per-domain server edits.

listen 80 default_server;
listen 443 ssl http2 default_server;
server_name _;

Only one Nginx site can be default_server for port 80 and one for port 443. If Nginx reports a duplicate default server, remove default_server from the other site or set LinkQR as the default site in the hosting panel.

For one customer domain, adding a specific hostname to server_name can work temporarily:

server_name youdomain.com customer-domain.com;

This is not the recommended SaaS setup because it requires editing Nginx for each customer domain.

Laravel rewrite rule

Keep the normal Laravel rewrite rule so custom-domain paths are sent to the app:

location / {
    try_files $uri $uri/ /index.php?$args;
}

SSL guidance

If the customer uses Cloudflare proxy, use SSL/TLS mode Full. Do not use Full (strict) unless the origin certificate is valid for that exact customer domain or the platform uses Cloudflare for SaaS/custom hostnames.

Do not use Flexible for HTTPS applications because it can cause redirect loops and insecure origin traffic.

Setup flow

1. Add the domain inside the Brand section.
2. Create the CNAME or A/AAAA DNS record.
3. Create the TXT verification record.
4. Wait for DNS propagation.
5. Verify the domain in LinkQR.
6. Assign the verified domain to a Link Bio page, QR campaign, or Short URL.
7. Test HTTPS and the correct route prefix: /s, /q, or /b.

Troubleshooting

• TXT not found: check whether the TXT record name is @ for root or the chosen subdomain name for subdomains.
• CNAME not found: root domains on Cloudflare may return A/AAAA because of CNAME flattening. Subdomains should show CNAME to youdomain.com.
• SSL pending: wait for DNS propagation and confirm Cloudflare SSL mode is compatible.
• 526 Invalid SSL certificate: Cloudflare is likely using Full strict and the origin certificate does not cover the custom domain. Use Full or configure a valid origin certificate.
• 1016 Origin DNS error: the DNS target is invalid or includes a URL path. Use only youdomain.com.
• App domain works but custom domain returns 404: the web server is not routing the customer hostname into the LinkQR app, or the domain is not verified in LinkQR.
• Wrong route prefix: short links use /s/{code}, QR campaigns use /q/{code}, and Bio pages use /b/{slug}.