new arch

README.md

@@ -1,2 +1,130 @@
-# local-dns
+# 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.