Environments

Overview

Environments represent deployment targets such as production, preview, staging, or a custom stage. Each environment has its own deployments, services, secrets, and domains.

Use environments.<env>.domains in hostess.yml to assign custom domains to services in a specific environment:

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

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

YAML Field

Deploying

Pass the target environment explicitly when deploying:

hostess deploy --env production
hostess deploy --env staging
hostess deploy --env preview

If --env is omitted, the CLI uses the most recently created environment in the project. On a standard new project, that is often preview, because it is created after production.

Per-Environment Domains

Custom domains can be configured at two levels.

Service-Level Domains

The domains field on a service is shorthand for production:

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

Environment-Level Domains

Use environments.<env>.domains when different environments need different hostnames:

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

Domain rules:

• Environment-level domains override service-level domains for that environment.
• Service-level domains applies only to production.
• A domain can appear in only one environment.
• Use custom domains for application services such as nextjs, fastapi, and custom.

Secrets

Secrets are scoped to environments through the CLI:

hostess secrets add STRIPE_KEY --value "sk_live_abc123" --envs production
hostess secrets add STRIPE_KEY --value "sk_test_xyz789" --envs staging,preview

This keeps production credentials separate from staging or preview credentials. See Secrets for the full guide.