> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker & HTTPS Setup

> Containerized development with local HTTPS

# Docker & HTTPS Setup

Configure Docker, Traefik, and local HTTPS for Overdeck workspaces.

## Overview

Overdeck uses Docker for isolated development environments and Traefik as a reverse proxy for local HTTPS. This enables:

* **Isolated workspaces** - Each feature branch runs in its own containers
* **Local HTTPS** - Trusted certificates for `.localhost` or custom domains
* **Automatic routing** - Traefik routes traffic based on container labels

## Prerequisites

* Docker Desktop (macOS/Windows) or Docker Engine (Linux)
* Docker Compose v2.x
* `mkcert` for local certificate generation

## Quick Setup

```bash theme={null}
# Install mkcert
brew install mkcert  # macOS
# or: sudo apt install mkcert  # Ubuntu/Debian

# Install the local CA
mkcert -install

# Run Overdeck's setup
pan install
pan doctor  # Verify setup
```

## Traefik Configuration

Overdeck manages Traefik configuration in `~/.overdeck/traefik/`:

```
~/.overdeck/traefik/
├── traefik.yml           # Static configuration
├── dynamic/              # Dynamic route configs (per-workspace)
│   └── feature-min-123.yml
└── certs/                # TLS certificates
    ├── localhost.pem
    └── localhost-key.pem
```

### Static Configuration

The main Traefik config (`~/.overdeck/traefik/traefik.yml`):

```yaml theme={null}
api:
  dashboard: true
  insecure: true

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"

providers:
  docker:
    watch: true
    exposedByDefault: false
  file:
    directory: /etc/traefik/dynamic
    watch: true

tls:
  stores:
    default:
      defaultCertificate:
        certFile: /certs/localhost.pem
        keyFile: /certs/localhost-key.pem
```

### Dynamic Configuration

Each workspace gets a dynamic config file. Example for `feature-min-123`:

```yaml theme={null}
http:
  routers:
    feature-min-123-frontend:
      rule: "Host(`feature-min-123.localhost`)"
      service: feature-min-123-frontend
      entryPoints:
        - websecure
      tls: {}

    feature-min-123-api:
      rule: "Host(`api-feature-min-123.localhost`)"
      service: feature-min-123-api
      entryPoints:
        - websecure
      tls: {}

  services:
    feature-min-123-frontend:
      loadBalancer:
        servers:
          - url: "http://feature-min-123-frontend:3000"

    feature-min-123-api:
      loadBalancer:
        servers:
          - url: "http://feature-min-123-api:8080"
```

## Certificate Generation

### Using mkcert

```bash theme={null}
# Generate certificates for localhost domains
cd ~/.overdeck/traefik/certs
mkcert localhost "*.localhost" 127.0.0.1 ::1

# Rename to expected names
mv localhost+3.pem localhost.pem
mv localhost+3-key.pem localhost-key.pem
```

### For Custom Domains

If using custom domains like `myapp.test`:

```bash theme={null}
# Generate certificates for custom domain
mkcert myapp.test "*.myapp.test"
```

## DNS Configuration

### Option 1: .localhost (Recommended)

Modern browsers resolve `*.localhost` to `127.0.0.1` automatically. No DNS config needed.

```yaml theme={null}
# In projects.yaml
dns:
  domain: localhost
  entries:
    - "{{FEATURE_FOLDER}}.localhost"
    - "api-{{FEATURE_FOLDER}}.localhost"
```

### Option 2: /etc/hosts

For custom domains, add entries to `/etc/hosts`:

```bash theme={null}
# Add manually or let Overdeck manage it
127.0.0.1 feature-min-123.myapp.test
127.0.0.1 api-feature-min-123.myapp.test
```

### Option 3: WSL2 Hosts Sync (Windows)

For WSL2, use the `wsl2hosts` sync method:

```yaml theme={null}
dns:
  sync_method: wsl2hosts
```

This syncs entries between WSL2's `/etc/hosts` and Windows' hosts file.

## Starting Traefik

### Via Dashboard

The dashboard starts Traefik automatically when you run `pan up`:

```bash theme={null}
pan up
# Traefik available at http://localhost:8080 (dashboard)
# HTTPS routing at https://*.localhost
```

### Manually

```bash theme={null}
# Start Traefik container
docker run -d \
  --name overdeck-traefik \
  --network overdeck \
  -p 80:80 -p 443:443 -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v ~/.overdeck/traefik:/etc/traefik:ro \
  -v ~/.overdeck/traefik/certs:/certs:ro \
  traefik:v2.10
```

## Workspace Container Setup

### Docker Compose Template

```yaml theme={null}
# infra/.devcontainer-template/docker-compose.yml.template
services:
  frontend:
    build:
      context: ./fe
      dockerfile: Dockerfile
    volumes:
      - ./fe:/app
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.{{FEATURE_FOLDER}}-fe.rule=Host(`{{FEATURE_FOLDER}}.localhost`)"
      - "traefik.http.routers.{{FEATURE_FOLDER}}-fe.entrypoints=websecure"
      - "traefik.http.routers.{{FEATURE_FOLDER}}-fe.tls=true"
      - "traefik.http.services.{{FEATURE_FOLDER}}-fe.loadbalancer.server.port=3000"
    networks:
      - overdeck

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    volumes:
      - ./api:/app
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.{{FEATURE_FOLDER}}-api.rule=Host(`api-{{FEATURE_FOLDER}}.localhost`)"
      - "traefik.http.routers.{{FEATURE_FOLDER}}-api.entrypoints=websecure"
      - "traefik.http.routers.{{FEATURE_FOLDER}}-api.tls=true"
      - "traefik.http.services.{{FEATURE_FOLDER}}-api.loadbalancer.server.port=8080"
    networks:
      - overdeck

networks:
  overdeck:
    external: true
```

### Network Setup

Create the shared Overdeck network:

```bash theme={null}
docker network create overdeck
```

All workspaces and Traefik connect to this network for routing.

## Troubleshooting

### "Connection refused" on HTTPS

1. Check Traefik is running:
   ```bash theme={null}
   docker ps | grep traefik
   ```

2. Check Traefik logs:
   ```bash theme={null}
   docker logs overdeck-traefik
   ```

3. Verify certificates exist:
   ```bash theme={null}
   ls ~/.overdeck/traefik/certs/
   ```

### "Certificate not trusted" warnings

1. Install mkcert's CA:
   ```bash theme={null}
   mkcert -install
   ```

2. Restart your browser

### Workspace containers not routable

1. Verify containers are on the overdeck network:
   ```bash theme={null}
   docker network inspect overdeck
   ```

2. Check container labels:
   ```bash theme={null}
   docker inspect <container> | grep -A 20 Labels
   ```

3. Check Traefik dashboard at [http://localhost:8080](http://localhost:8080)

### Port conflicts

If ports 80/443 are in use:

```bash theme={null}
# Find what's using the ports
lsof -i :80
lsof -i :443

# Common culprits: Apache, nginx, other dev servers
```

### WSL2-specific issues

See [Troubleshooting](/reference/troubleshooting#wsl2-stability-issues-windows-users) for WSL2-specific networking and performance issues.

## Best Practices

### Resource Management

* **Limit concurrent workspaces** - Each workspace uses memory
* **Use shared volumes** - Cache npm/maven dependencies across workspaces
* **Clean up old containers** - Run `docker system prune` periodically

### Security

* **Don't expose Traefik externally** - Keep it bound to localhost
* **Use unique certificates per environment** - Don't share between machines
* **Regenerate certificates periodically** - mkcert certs expire after \~1 year

### Performance

* **Use Docker volumes for node\_modules** - Avoid mounting from host
* **Adjust Vite polling interval** - See [Troubleshooting](/reference/troubleshooting#slow-vitereact-frontend-with-multiple-workspaces)
* **Monitor container resources** - Use `docker stats`

## Related Guides

* [Polyrepo Configuration](/configuration/polyrepo) - Multi-repository workspaces
* [Workspaces](/features/workspaces) - Workspace management
* [Troubleshooting](/reference/troubleshooting) - Common issues