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:
   ```bash
   git clone <repository-url> local-dns
   cd local-dns
   ```

2. Initialize the project:
   ```bash
   ./scripts/00-init.sh
   ```
   This creates a `.env` file from `.env.example` and sets up the directory structure.

3. Generate TLS certificates:
   ```bash
   ./scripts/01-generate-cert.sh
   ```
   This creates trusted certificates for your local domain.

4. Start the core infrastructure:
   ```bash
   docker compose up -d
   ```

5. Add your first service (example: Gitea on port 3000):
   ```bash
   ./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:
   ```bash
   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:

```bash
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:
   ```powershell
   # 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**: 
  ```bash
  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`:
   ```ini
   PUBLIC_DOMAIN=yourdomain.com
   LETSENCRYPT_EMAIL=you@yourdomain.com
   ```

2. Re-run initialization:
   ```bash
   ./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.