local-dns/README.md

Local DNS Services with Docker

This project provides a local development infrastructure with automatic DNS resolution for custom domains (e.g., .mikan or .local) and valid HTTPS certificates.

Features

• Automatic DNS resolution for *.yourdomain and *.yourdomain.local
• Valid HTTPS certificates for local domains using mkcert
• Easy service deployment with VIRTUAL_HOST environment variables
• Ready for future expansion: public domains, Let's Encrypt, Tailscale
• Single-command service creation

Requirements

• Docker and Docker Compose
• mkcert installed on the host system

Quick Start

1. Clone this repository and enter the directory:

   git clone <repository-url> local-dns
   cd local-dns
   

2. Initialize the project:

   ./scripts/00-init.sh
   

   This creates a .env file from .env.example and sets up the directory structure.

3. Generate TLS certificates:

   ./scripts/01-generate-cert.sh
   

   This creates trusted certificates for your local domain.

4. Start the core infrastructure:

   docker compose up -d
   

5. Add your first service (example: Gitea on port 3000):

   ./scripts/add-service.sh gitea 3000
   

   Then edit services/gitea/docker-compose.yml to set the correct image and volumes.

6. Start the new service:

   docker compose -f docker-compose.yml -f services/gitea/docker-compose.yml up -d
   

7. Visit https://gitea.yourdomain in your browser (replace yourdomain with your configured domain).

Configuration

Edit the .env file to customize your setup:

• LOCAL_DOMAIN: Your local domain suffix (default: mikan)
• PUBLIC_DOMAIN: Optional public domain for Let's Encrypt certificates
• LETSENCRYPT_EMAIL: Email for Let's Encrypt notifications
• Network settings (NGINX_IP, DNSMASQ_IP, etc.)

After changing .env, re-run the initialization and certificate scripts.

DNS Setup

Linux/macOS

Use the included dnsmasq service for automatic DNS resolution:

docker compose -f docker-compose.yml -f docker-compose.dnsmasq.yml up -d

Then configure your system to use 10.0.0.2 as the primary DNS server.

Windows (WSL2)

Windows reserves port 53, so dnsmasq cannot run on the host. Instead:

1. Work inside WSL2
2. Manually add entries to the Windows hosts file:

   # Run PowerShell as Administrator
   Add-Content -Path "C:\Windows\System32\drivers\etc\hosts" -Value "127.0.0.1 gitea.mikan"
   Add-Content -Path "C:\Windows\System32\drivers\etc\hosts" -Value "127.0.0.1 gitea.mikan.local"
   

Certificate Trust

After running ./scripts/01-generate-cert.sh, install the root certificate on your devices:

• Linux: Depends on distribution (usually via update-ca-certificates)
• macOS:

  sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca/rootCA.pem
  

• Windows:
  1. Copy ca/rootCA.pem to Windows
  2. Open certmgr.msc
  3. Import into "Trusted Root Certification Authorities"

Adding Public Domain Support

To enable Let's Encrypt certificates for a public domain:

1. Set in .env:

   PUBLIC_DOMAIN=yourdomain.com
   LETSENCRYPT_EMAIL=you@yourdomain.com
   

2. Re-run initialization:

   ./scripts/00-init.sh
   ./scripts/01-generate-cert.sh
   

3. New services will automatically request Let's Encrypt certificates for the public domain.

Service Management

• Add a service: ./scripts/add-service.sh <name> <port>
• Start all: docker compose up -d
• Start with dnsmasq: docker compose -f docker-compose.yml -f docker-compose.dnsmasq.yml up -d
• Stop all: docker compose down

All service data is stored in the services/ directory and persists between restarts.