Connect a website domain

A published website can use your installation's address or a separate HTTPS hostname. A separate hostname needs DNS and web-server configuration.

For: the developer or hosting administrator who maintains the installation. What you need: control of DNS, the HTTPS virtual host and the installation's environment configuration.

The website editor saves a hostname. It does not buy domains, edit DNS or obtain certificates.

Use the installation address

Leave Custom domain empty to use the default path. For example:

https://office.example.com/site/northwind-studio/en
https://office.example.com/site/northwind-studio/nl/contact

The website root opens its default language. Each enabled language has its own page addresses.

Public /site/... requests cannot fall through to staff login, API, MCP or installer routes. Pepper removes session and authorization context before rendering them.

On this shared hostname, browsers can still send an existing installation cookie with a website request. The public website ignores that cookie.

Public page responses do not create a staff session or send a session cookie. Keep using the installation address for staff work.

Customer account addresses

Customer accounts use separate sessions. Their HTTPS addresses are:

Use an enabled language code. A website account follows the published website's design and languages; the installation account needs no published website.

Account responses can set their own secure, host-only cookie. They ignore staff authentication and cannot authorize staff routes.

Each custom hostname requires a separate sign-in. Moving the website address or withdrawing it invalidates access through the previous website address.

Account responses and downloads use no-store. Exclude account paths from proxy and CDN caching. Search exclusion alone does not protect private data.

Keep HTTPS and the Customers module available. See Manage customer accounts.

Prepare a separate hostname

Keep your existing staff address available while configuring the website hostname.

1. Choose an exact hostname, such as www.example.com.
2. Open the website's Settings and read Connect a domain.
3. Point DNS to the configured target or the public addresses supplied by your host.
4. Configure the public document root and the request routing described below.
5. Install a valid HTTPS certificate for that hostname.
6. If a proxy terminates HTTPS, make sure Pepper recognizes the original request as HTTPS.
7. Keep APP_URL set to the staff installation's address.
8. Set SESSION_DOMAIN=null in the installation's .env file.
9. Apply the environment change through your normal deployment process.

For a subdomain such as www, CNAME target shows the installation hostname configured by its operator. Copy that target into DNS.

For a root domain, ask your provider about ALIAS or ANAME. Otherwise use the public A or AAAA addresses your host supplies.

Pepper shows an A or AAAA value only when the installation is explicitly configured at a public IP address. Confirm its stability with your host.

A hostname alone does not reveal a trusted server IP. Local, private or unconfigured installation addresses provide no public DNS target.

Saving the hostname changes no DNS record. Pepper does not verify DNS propagation, server routing or the HTTPS certificate.

For an installation using cached Laravel configuration, rebuild the configuration cache after changing .env:

php artisan config:cache

Use the hosting account and PHP version that normally run this installation. Do not display the environment file or its keys in public diagnostics.

SESSION_DOMAIN=null makes the session cookie specific to the staff hostname. Do not set a parent domain such as .example.com.

Pepper refuses custom-domain publication when session.domain is configured. Removing a broad cookie domain is required even for another hostname under the same parent domain.

If the installation previously issued parent-domain cookies, clear those old cookies from staff browsers and sign in again. Changing configuration does not remove existing browser cookies.

Route icons and discovery through Pepper

The server must send website pages, icons, share images and discovery requests to Pepper before checking for static files. Sharing a document root is insufficient.

Keep the original hostname and request URI when forwarding a request. Pepper uses them to admit the published website.

Apache

Use the shipped .htaccess files. The preferred document root is the installation's public directory. Shared-host installations also need the root .htaccess.

Enable Apache rewrite support and allow these files to apply. Do not replace their website rules with a static-file shortcut.

The rules route /site/, /_assets/, /_account/ and the icon and discovery aliases through index.php before the existing-file check. Direct /public/... variants also need admission.

Check both the public-directory and shared-host arrangements when changing your deployment. An application response test alone does not test Apache's static-file routing.

Nginx

Nginx does not read .htaccess. Add equivalent rules before generic image, font or other static-file rules.

This example uses the application's public directory as the document root. Keep your existing PHP handler and FastCGI socket.

location ^~ /_assets/ { rewrite ^ /index.php last; }
location ^~ /site/ { rewrite ^ /index.php last; }

location ^~ /_account/ { rewrite ^ /index.php last; }
location ^~ /public/_assets/ { rewrite ^ /index.php last; }
location ^~ /public/site/ { rewrite ^ /index.php last; }

location ^~ /public/_account/ { rewrite ^ /index.php last; }

# Put this before generic static-extension regex locations.
location ~ ^/(?:public/)?(?:favicon\.(?:ico|svg)|icon\.svg|favicon-(?:16x16|32x32|48x48)\.png|apple-touch-icon\.png|android-chrome-(?:192x192|512x512)\.png|(?:app|site|manifest)\.webmanifest|robots\.txt|sitemap\.xml|llms\.txt)$ {
    rewrite ^ /index.php last;
}

Retain the original $request_uri as FastCGI's REQUEST_URI. Preserve the incoming Host through your established proxy configuration.

Check for conflicting exact locations, earlier regex rules or longer ^~ locations. Those can take precedence over this example.

Do not let a generic try_files or extension rule turn a virtual /_assets/*.png address into a static 404.

Proxies, CDNs and unknown hosts

Forward these requests to the origin with the original Host, URI and conditional request headers. Preserve no-cache, must-revalidate and ETag handling.

Do not give generated images independent cache freshness because their address contains a hash. Source withdrawal must reach Pepper before another response is served.

Purge older cached Pepper icons and manifests from customer hostnames when changing this routing.

The alias rules do not restrict every other static path. For complete hostname isolation, reject unknown hosts at your server or CDN.

Alternatively, use dedicated customer-host virtual hosts that forward every request through Pepper's host admission. A shared static document root alone does not provide that isolation.

Check the deployed routes

Before publication, verify these requests on your actual server:

Check GET and HEAD. Public pages and generated images must not set a session cookie. A generated image response includes the correct content type and nosniff.

Each path website has an informational robots.txt beneath its base. Only the installation hostname's root robots.txt governs that shared host.

Search services can treat a favicon or site name as belonging to the hostname. A separate path does not promise a separate search-result identity.

Publish at the hostname

1. Open the website and choose Settings.
2. Enter the hostname in Custom domain.
3. Update each selected widget's allowed origins to include https://www.example.com where required.
4. Click Save draft.
5. Click Publish website and inspect the reviewed address.
6. Confirm publication.
7. Open the HTTPS address in a separate browser session.
8. Check each language, page and connected widget.

Enter only a lowercase hostname. Schemes, paths, ports, IP addresses and wildcards are rejected.

Use the default path for the installation's own hostname. Another website cannot use an already-published hostname or website path.

Requests admitted by Pepper on a custom hostname serve that website. Staff sign-in, API, MCP and installation routes remain unavailable there.

Widget frames use the installation's public widget service. Keep the installation's HTTPS address reachable, and preserve each widget's own sign-in and consent requirements.

Check failures and later changes

Publishing a page-path change creates a 301 redirect to that page's current path for 12 months. Descendant paths follow a moved parent.

Changing the website slug or hostname creates no redirect from the old website address. Configure any such redirect with your host after checking both addresses.

After restoring a backup, review website hostnames, DNS, HTTPS and widget origins before opening the installation. Environment and server configuration are separate from the backup.

See Build and publish a website for drafts, languages, history and withdrawal.