Introduction

Domain configuration in Docker Compose usually means mapping friendly hostnames to services during local development and staging. Docker networking already provides service-name DNS inside the Compose network, while browser-accessible custom domains usually require host mapping and a reverse proxy. A clean setup improves local parity with production routing.

Understand Internal Versus External Domain Resolution

Inside a Compose network, containers can resolve each other by service name.

1services:
2  api:
3    image: my-api
4  web:
5    image: my-web

Here, web can call http://api:8080 without extra DNS configuration.

External access from your laptop browser is different. Host OS needs to resolve names such as app.local to local proxy endpoints.

Basic Compose Hostname and Aliases

You can set container hostname and network aliases for internal discovery.

1services:
2  app:
3    image: nginx:alpine
4    hostname: app
5    networks:
6      default:
7        aliases:
8          - app.internal
9          - web.internal

These aliases work inside Docker network scope, not automatically on your host machine.

Configure External Domains with Reverse Proxy

For realistic domain routing, use Traefik or Nginx as front proxy and route by host header.

Compose example with Traefik:

1services:
2  traefik:
3    image: traefik:v3.0
4    command:
5      - --providers.docker=true
6      - --entrypoints.web.address=:80
7    ports:
8      - "80:80"
9    volumes:
10      - /var/run/docker.sock:/var/run/docker.sock:ro
11
12  app:
13    image: nginx:alpine
14    labels:
15      - traefik.http.routers.app.rule=Host(`app.local`)
16      - traefik.http.routers.app.entrypoints=web

Then map domain in host file:

127.0.0.1 app.local

Now browser requests to http://app.local route to the correct container via Traefik.

Multi-Service Domains and Subdomains

You can route multiple services by subdomain.

1services:
2  api:
3    image: my-api
4    labels:
5      - traefik.http.routers.api.rule=Host(`api.local`)
6
7  frontend:
8    image: my-frontend
9    labels:
10      - traefik.http.routers.frontend.rule=Host(`www.local`)

Host mappings:

127.0.0.1 api.local
127.0.0.1 www.local

This mirrors production-style host-based routing with separate services.

HTTPS in Local Compose Environments

For local TLS testing, use mkcert or self-signed certs and configure proxy TLS entrypoints.

Example concepts:

• generate local trusted certs,
• mount cert files into proxy container,
• configure router TLS options.

This helps test secure cookie behavior, OAuth callbacks, and mixed-content rules earlier.

Useful DNS and Networking Diagnostics

When domain routing fails, inspect three layers:

1. host name resolution,
2. proxy route rules,
3. container network connectivity.

Helpful commands:

docker compose ps
docker compose logs traefik
curl -H "Host: app.local" http://127.0.0.1

Inside container DNS checks:

docker compose exec app getent hosts api

These quickly isolate whether issue is DNS, routing config, or service health.

Local DNS Alternatives to Manual Host File Edits

For teams with many services, manual host-file entries do not scale well. Lightweight local DNS tools such as dnsmasq can route wildcard domains like *.dev.local to 127.0.0.1.

Typical approach:

• map wildcard local domain to loopback,
• configure reverse proxy to route by host header,
• use consistent subdomain conventions per service.

This reduces setup friction for new developers and keeps local domain rules consistent across projects.

Document the chosen local domain convention in project onboarding notes so everyone uses the same URLs and proxy rules.

Common Pitfalls

A common mistake is expecting Compose network aliases to work from host browser. They only resolve inside Docker networks unless host DNS is configured.

Another issue is forgetting host file entries for local custom domains. Without explicit mapping, requests never reach local proxy.

Developers also bind multiple proxies to port 80 simultaneously, causing hidden startup failures. Ensure a single component owns each host port.

Summary

• Compose service names provide internal DNS automatically.
• External custom domains require host mapping and usually a reverse proxy.
• Use proxy host-based rules for multi-service local routing.
• Add TLS locally when testing security-sensitive flows.
• Debug by checking host DNS, proxy rules, and container connectivity in order.