Host DNS Setup

By default, Simfra service DNS names (ALB endpoints, RDS endpoints, etc.) use the simfra.dev domain suffix. These names are resolved inside Docker containers by Simfra's built-in DNS. To resolve them from your host machine, you have two options.

Prerequisites

  • Simfra running with SIMFRA_DOCKER=true
  • Admin/sudo access on your host (for modifying /etc/hosts or DNS configuration)

Basic: /etc/hosts

For most use cases, a single hosts entry is sufficient:

127.0.0.1 simfra.local

This lets you reach Simfra services using simfra.local:{port}. The port is included in API responses (e.g., the ALB DNS name, the RDS endpoint).

This is the recommended approach for getting started. It does not resolve service-specific DNS names like my-alb-123.elb.us-east-1.simfra.dev, but you can always use simfra.local:{port} instead.

Advanced: Forward *.simfra.dev to Simfra DNS

To resolve the actual service DNS names (e.g., my-alb-123.elb.us-east-1.simfra.dev, mydb.abc123.us-east-1.rds.simfra.dev), forward the simfra.dev domain to Simfra's DNS container.

Find the DNS Port

Each account has a DNS container. Find its host port:

curl http://localhost:4599/_simfra/dns/000000000000
# → {"port": 10000}

The port comes from the SIMFRA_DNS_PORT_RANGE (default 10000-10099). The first account's DNS container typically gets port 10000.

macOS (dnsmasq via Homebrew)

brew install dnsmasq
echo "server=/simfra.dev/127.0.0.1#10000" >> $(brew --prefix)/etc/dnsmasq.conf
sudo brew services restart dnsmasq

Then configure macOS to use dnsmasq for the simfra.dev domain:

sudo mkdir -p /etc/resolver
echo "nameserver 127.0.0.1" | sudo tee /etc/resolver/simfra.dev
echo "port 53" | sudo tee -a /etc/resolver/simfra.dev

Verify:

dig my-alb-123.elb.us-east-1.simfra.dev @127.0.0.1

Linux (systemd-resolved)

Create a dummy network interface and configure split DNS:

# Forward simfra.dev queries to Simfra's DNS
sudo resolvectl dns simfra 127.0.0.1:10000
sudo resolvectl domain simfra ~simfra.dev

Or add a drop-in configuration file:

sudo mkdir -p /etc/systemd/resolved.conf.d
cat <<EOF | sudo tee /etc/systemd/resolved.conf.d/simfra.conf
[Resolve]
DNS=127.0.0.1#10000
Domains=~simfra.dev
EOF
sudo systemctl restart systemd-resolved

Verify:

resolvectl query my-alb-123.elb.us-east-1.simfra.dev

When You Need Advanced DNS

Advanced DNS setup is useful when:

  • Your application resolves service endpoints by DNS name (e.g., connecting to mydb.abc123.us-east-1.rds.simfra.dev instead of simfra.local:10400)
  • You are testing Route53 hosted zone resolution from the host
  • You want nslookup and dig to resolve Simfra domains

For most development workflows, the basic /etc/hosts entry is sufficient. Service ports are always included in API responses, so you can connect using simfra.local:{port}.

Next Steps