Support/How to configure custom domains and SSL

How to configure custom domains and SSL

Point a production HTTPS domain at BaseBuddy, check proxy headers, and verify local password sign-in before editors use it.

Use this guide when BaseBuddy is already deployed and you want editors to use a production domain such as https://cms.example.com.

You will point DNS at the host, terminate HTTPS at your platform or reverse proxy, forward traffic to BaseBuddy's internal app port, and test sign-in before sharing the domain.

BaseBuddy listens internally on port 8080 when it runs with pnpm start. TLS/SSL certificates are handled by your host, load balancer, or reverse proxy in front of the app.

Before you start

You need:

A running BaseBuddy deployment.
The domain or subdomain editors will use.
Access to DNS for that domain.
Access to your hosting platform or reverse proxy.
Access to the production host or shell where you can run setup checks.

For deployment-specific setup, use How to deploy BaseBuddy to a VPS with Docker or How to deploy BaseBuddy with Dokploy. For the broader production checklist, see Deployment.

Point DNS at your host

Create the DNS record your host expects.

Most setups use one of these:

Domain shape	Common DNS record
`cms.example.com`	`CNAME` to your platform hostname, or `A`/`AAAA` to your server IP
`example.com`	`A`/`AAAA` records to your server IP, or the provider's apex-domain record type

Use the production BaseBuddy domain for the app people sign in to. Do not send invite links from a temporary preview URL unless that preview URL is the one editors will keep using.

After saving DNS, wait for the record to resolve from outside your server. Your host may show the domain as pending until DNS propagation reaches it.

Enable HTTPS before public traffic

Enable SSL or HTTPS for the domain in your hosting platform, load balancer, or reverse proxy.

Confirm this URL opens BaseBuddy over HTTPS:

texthttps://cms.example.com

Replace https://cms.example.com with your real production domain.

Production BaseBuddy responses include HSTS headers. HSTS tells browsers to keep using HTTPS for the domain after they see a secure response. Confirm the certificate and HTTPS routing are correct before you send public traffic or invite editors.

Do not use plain HTTP for production sign-in, invites, or editor sessions.

Forward the domain to BaseBuddy

Configure your host or reverse proxy to send public HTTPS requests to the BaseBuddy app running internally on port 8080.

The public request should be:

texthttps://cms.example.com

The internal upstream should be the running app, for example:

texthttp://127.0.0.1:8080

or the equivalent internal service name and port in your platform.

Make sure the proxy forwards the public host and protocol correctly. BaseBuddy uses browser-facing request information for same-origin setup requests and safe sign-in return paths.

Your reverse proxy should strip or overwrite any client-supplied x-forwarded-* headers before forwarding the request, then set trusted forwarded values itself. In practice, that means the app should receive the real public host, such as cms.example.com, and the real public protocol, https, from the proxy you control.

If uploads fail after the domain works, also check proxy request-size limits. BaseBuddy can accept larger media and file uploads, but the proxy can reject the request before BaseBuddy sees it.

BaseBuddy installs use local email and password sign-in. Supabase Auth URL settings are not required for current sign-in.

Open the final production login page:

texthttps://cms.example.com/login

Sign in with the owner account created during setup. Successful sign-in should open /projects or the safe internal page you requested before login.

Then create a test invite from Project Settings and open it in a private browser window. The invite link should use the same production domain and return to the invite page after sign-in.

For the full checklist, use How to verify BaseBuddy sign-in setup.

Restart after deployment changes

Restart or redeploy BaseBuddy after changes to environment variables, host routing, proxy settings, or persistent storage mounts.

BaseBuddy reads install credentials from environment variables when the server starts. Project rows do not store deployment credentials.

Then run setup checks from the deployed environment or from a shell with the same production env values:

shpnpm setup:check

Use How to run setup checks after deployment or upgrade for the verification flow.

Verify the domain before editors use it

Open the production domain in a private browser window.

Confirm:

The address bar shows https://cms.example.com.
The page does not redirect to localhost, a preview URL, or the Supabase project URL.
Password sign-in starts and finishes on the production domain.
/projects loads after sign-in.
Setup checks pass in the deployed environment.

Then verify the invite flow:

Sign in as a project owner or manager.
Create a test invite for an email address you control.
Open the invite link in a private browser window.
Complete sign-in.
Confirm the browser returns to the invite page or project access flow on the production domain.

Do this before inviting real editors. Invite links should use the final HTTPS domain, not a temporary host.

Common problems

Problem	What it usually means	What to do
The domain opens the wrong app	DNS or platform domain routing points somewhere else	Check the DNS record and the app attached to the domain
HTTPS fails or shows a certificate warning	SSL is not issued, not attached, or issued for a different hostname	Fix HTTPS at the host or proxy before sending traffic
The app loads, but sign-in returns to the wrong place	The login return path was unsafe, stale, or opened from the wrong host	Start from the final production domain and test `/login` again
Sign-in works locally but not on the domain	Production cannot read the same config file, env, host, or protocol	Check persistent storage, env values, and forwarded headers
State-changing actions fail with origin or permission-like errors	The app may be receiving the wrong public host or protocol	Strip client-supplied `x-forwarded-*` headers and set trusted forwarded host/protocol at the proxy
Uploads fail only on the production domain	The proxy or host request-size limit is lower than the upload	Raise the host/proxy body-size limit for the uploads you support

After the domain, HTTPS, sign-in, invite return path, and setup checks are clean, editors can use the production URL for normal BaseBuddy work.