Custom Domains

Overview Enterprise - Requires the Enterprise plan

A custom domain lets a schedule be reached at its owner's own address (for example events.example.com) instead of the default subdomain.yourdomain.com URL.

Owners choose the mode themselves. In the schedule's settings, on the General tab, the Schedule URL has an Edit button that reveals a Mode chooser with three options.

What changes on a direct custom domain

Direct mode is not only a different address. Once the domain is active, several parts of the product behave differently on that host:

• The custom domain becomes the SEO canonical for that schedule's guest portal, and the schedule serves its own /sitemap.xml on that host. Your platform's global sitemap never lists custom-domain URLs. In Redirect mode the subdomain stays canonical, because the custom domain only 301s away from itself.
• Ads are never served. If you run AdSense on free schedules, ad slots are suppressed on any custom domain, whatever the schedule's plan. Serving ads on a domain you do not own would breach AdSense policy.
• The accommodation map only runs on the owner's own affiliate ID. Your instance-wide Stay22 fallback ID is never used on a customer's custom domain, so the map simply does not render for a schedule that has not set its own ID.
• The embedded Google map is omitted on event pages served from a custom domain, so your Maps API key is never handed out on a host you do not control. The address and its link are still shown.
• Sign-in, admin and follow links stay on the app subdomain. Only the schedule's own URLs are rewritten to the custom domain, so the session cookie keeps working.

Prerequisites

Both modes

• Hosted mode - your deployment must run with IS_HOSTED=true. The mode chooser is only rendered in hosted mode, and the request-time domain lookup is skipped entirely otherwise. A selfhosted install is path-routed on the one domain you point at it, so it has nothing to configure here.
• An Enterprise schedule - the plan gate applies per schedule, not per deployment.

Direct mode only

• DigitalOcean App Platform - your app must be deployed on DigitalOcean App Platform, which is what provisions and renews the SSL certificate for each customer domain.
• DO API token - a DigitalOcean personal access token scoped to read and update on the app resource. Adding and removing a domain is a read of the current app spec followed by a write of the amended one.
• App ID - the ID of your DigitalOcean App Platform app.
• App hostname - the app's .ondigitalocean.app starter domain, which is the CNAME target customers point at.

Environment Setup

Add the following variables to your .env file:

DO_API_TOKEN=your_digitalocean_api_token
DO_APP_ID=your_app_id
DO_APP_HOSTNAME=your-app.ondigitalocean.app

The three values are read once into the digitalocean block of config/services.php, and they do different jobs:

• DO_API_TOKEN and DO_APP_ID together decide whether provisioning runs at all. If either is missing, saving a domain, re-provisioning and the status sync all quietly no-op, and the domain never leaves the pending state.
• DO_APP_HOSTNAME decides whether Direct mode is offered to owners, and is the value shown in the copy-to-clipboard CNAME instructions.

How It Works

Redirect Mode

The owner stores their domain and sets up a Cloudflare page rule that 301 redirects it to their subdomain.yourdomain.com URL. Nothing is registered with DigitalOcean, no certificate is issued by you, and no status is tracked, so the Status column in the admin panel stays empty for these schedules. The subdomain remains the canonical URL, since the custom domain never renders a page itself.

Direct Mode

When an owner saves their domain in Direct mode:

1. The domain is normalized to https://host, its hostname is stored separately for fast lookup, and it is rejected if another schedule already claims it or if the hostname contains eventschedule.com.
2. The hostname is added to your DigitalOcean App Platform app spec over the API, and the schedule's domain status is set to pending (or failed if the API call did not succeed).
3. The owner adds a CNAME record pointing at your app's hostname.
4. DigitalOcean verifies the record and provisions an SSL certificate.
5. A scheduled sync notices the domain has gone live and flips the status to active.
6. From then on, requests arriving on the custom domain are matched to the schedule and served, and the schedule's own subdomain URLs in the response are rewritten to the custom domain.

Domain status lifecycle

Direct-mode domains carry a status. Owners and admins see a coloured badge; the underlying value is what filters and the middleware key off.

The transition out of pending is done by a scheduled command that runs every five minutes on hosted deployments:

php artisan app:sync-domain-statuses

It reads every domain on your app from the DigitalOcean API and, for each schedule still pending, marks it active once DigitalOcean reports the domain as live, or failed if the domain is no longer on the app at all. If the API returns nothing at all it stops rather than marking everything failed, so an API outage cannot take working domains offline. It needs your cron entry (* * * * * php artisan schedule:run) to be running.

DNS Setup for Customers

When an owner selects Direct mode, the settings page shows these steps and the exact hostname to copy. They need to create one CNAME record at their domain registrar:

1. Log in to the domain registrar (e.g. GoDaddy, Namecheap, Cloudflare).
2. Open the DNS settings for the domain.
3. Add the CNAME record above.
4. Save, and wait for DNS to propagate. SSL is provisioned automatically once DigitalOcean can resolve the record.

Admin Management

Every schedule with a custom domain, in either mode, is listed at /admin/domains, reached from Manage > Domains in the admin navigation. The tab is hosted-only and admin-only.

Reading the page

• Summary cards - Total (every schedule with a custom domain), Direct, Active and Setting up... The last three count direct-mode schedules only.
• Search and filters - search by schedule name, subdomain or domain, and filter by mode or by status.
• Domain table - Schedule, Custom Domain, Mode, Status and DO Status, 20 rows to a page. DO Status is the live phase read straight from the DigitalOcean API on page load, so it is the column to trust when the stored status looks wrong. It is blank if the API is unreachable or unconfigured.

Actions

• Re-provision - removes and re-adds the domain to DigitalOcean and resets the status to pending. Use it when SSL provisioning gets stuck or after fixing a bad DNS record. Direct mode only.
• Remove - removes the domain from DigitalOcean and clears the schedule's domain, mode, host and status, sending it back to its subdomain URL. This is also how you take a domain off a schedule that has dropped off Enterprise.

Both actions are written to the audit log, and both clear the middleware's cached lookup, so the change takes effect on the next request rather than after 10 minutes.

Troubleshooting