Custom Domains

Overview

Custom domains let you serve application services from branded domain names like myapp.com or api.myapp.com. Public application services can also receive generated hostess.run URLs, so you can use the generated URL while DNS is being configured and keep it available after your custom domain is active.

Hostess handles everything related to HTTPS — TLS certificates are automatically provisioned via Let's Encrypt and renewed before expiration. You just need to configure a DNS record.

How It Works

When you add a custom domain to a service, Hostess:

1. Registers the domain in its routing layer so incoming requests for that domain are directed to the correct service.
2. Provisions a TLS certificate via Let's Encrypt using HTTP-01 challenge validation.
3. Serves HTTPS traffic using the provisioned certificate, with automatic HTTP-to-HTTPS redirects.
4. Renews the certificate automatically before it expires (certificates are valid for 90 days; Hostess renews them at 60 days).

Hostess manages certificate provisioning, TLS settings, and renewals automatically.

Adding Domains via hostess.yml

There are two ways to configure custom domains in your hostess.yml file:

Service-Level Domains (Production Shorthand)

The simplest way to add custom domains is directly on the service definition. This applies the domains to the production environment only:

services:
  frontend:
    type: nextjs
    build:
      source: ./frontend
    domains:
      - myapp.com
      - www.myapp.com

  api:
    type: fastapi
    build:
      source: ./backend
    domains:
      - api.myapp.com

This is the most common approach when you only need custom domains in production.

Environment-Level Domains

For per-environment domains (e.g., different domains for staging vs. production), configure them in the environments section:

environments:
  production:
    domains:
      frontend: [myapp.com, www.myapp.com]
      api: [api.myapp.com]

  staging:
    domains:
      frontend: [staging.myapp.com]
      api: [api-staging.myapp.com]

services:
  frontend:
    type: nextjs
    build:
      source: ./frontend

  api:
    type: fastapi
    build:
      source: ./backend

Combining Both Approaches

You can use service-level domains for production and environment-level domains for other environments:

environments:
  staging:
    domains:
      frontend: [staging.myapp.com]

services:
  frontend:
    type: nextjs
    build:
      source: ./frontend
    domains:
      - myapp.com          # Production only (shorthand)
      - www.myapp.com      # Production only (shorthand)

Adding Domains via CLI

You can also add custom domains using the Hostess CLI without modifying your hostess.yml:

# Add a production domain
hostess domains add --service frontend --env production myapp.com

# Add a staging domain
hostess domains add --service frontend --env staging staging.myapp.com

# List all domains for the project
hostess domains list

# Remove a domain
hostess domains remove myapp.com

See the CLI domains reference for all available commands and options.

DNS Configuration

After adding a custom domain, you need to create a DNS record that points your domain to the Hostess routing endpoint. The record type depends on your domain:

CNAME Record (Recommended)

For subdomains (e.g., app.myapp.com, api.myapp.com, www.myapp.com), create a CNAME record:

Type:  CNAME
Name:  app.myapp.com
Value: ingress.hostess.run

Apex Domains (Root Domains)

For apex domains (e.g., myapp.com without a subdomain), use the apex record option your DNS provider offers for hostname targets, such as CNAME flattening, ALIAS, or ANAME. The Hostess target stays the same:

Type:  CNAME
Name:  myapp.com
Value: ingress.hostess.run

Your DNS provider may show a different record type for apex domains, but the value should still point at ingress.hostess.run.

DNS Examples by Provider

Per-Environment Domains

Different environments can have different custom domains. This is useful for giving staging its own branded URL while keeping production on the primary domain:

environments:
  production:
    domains:
      frontend: [myapp.com, www.myapp.com]
      api: [api.myapp.com]

  staging:
    domains:
      frontend: [staging.myapp.com]
      api: [api-staging.myapp.com]

Each environment's domains need their own DNS records:

# Production
CNAME myapp.com       → ingress.hostess.run
CNAME www.myapp.com   → ingress.hostess.run
CNAME api.myapp.com   → ingress.hostess.run

# Staging
CNAME staging.myapp.com     → ingress.hostess.run
CNAME api-staging.myapp.com → ingress.hostess.run

Auto-Generated URLs

Public application services and public ports receive generated URLs on the hostess.run domain:

https://{project}-{service}-{nanoID}.hostess.run

For example, a public frontend and public API can have URLs like:

https://my-app-frontend-k7xm9p2q.hostess.run
https://my-app-api-a3x9d2m1.hostess.run

These URLs point to the active deployment for that service. Custom domains are an addition, so generated URLs and custom domain URLs can work side by side.

Validation Rules

Custom domains must follow these rules:

Valid Examples

domains:
  - myapp.com
  - www.myapp.com
  - api.myapp.com
  - staging.myapp.com
  - app.internal.myapp.com

Use Domain Names Only

domains:
  - myapp.com
  - api.myapp.com
  - staging.myapp.com

Troubleshooting

DNS Propagation Delays

After creating a CNAME record, it can take time for DNS changes to propagate. While most changes propagate within a few minutes, it can take up to 48 hours in some cases.

What to do:

• Wait 5-10 minutes after creating the DNS record, then check again.
• Use a DNS lookup tool to verify your record is visible: dig CNAME myapp.com or check dnschecker.org.
• If the record is visible in DNS lookups but Hostess still shows it as pending, wait a few more minutes — Hostess checks DNS periodically.

TLS Certificate Provisioning Delays

TLS certificate provisioning typically takes 1-2 minutes after DNS verification succeeds.

What to do:

• Verify that DNS is correctly configured (the CNAME points to ingress.hostess.run).
• If using Cloudflare, use DNS-only mode (grey cloud).
• Check whether the domain is already connected to another Hostess project or another platform.
• Redeploy your service — this can trigger a new certificate provisioning attempt.

Domain Conflicts

Each domain maps to one service in one environment across Hostess.

What to do:

• Check if the domain is already configured in another project or environment.
• If you have moved the domain from one service to another, remove it from the old service first.
• Contact support for help with ownership checks.

Common Mistakes