130 lines
3.7 KiB
Markdown
130 lines
3.7 KiB
Markdown
# 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. |