Server Context

This guide documents the server environment for agents working on this system. Understanding this context is essential before making changes.

Docker Containers

Service	Container	Image	Purpose
traefik	traefik	traefik:latest	Reverse proxy, SSL termination
docs	docs	docs-starlight	Documentation site (Starlight)
n8n	n8n	n8nio/n8n:latest	Workflow automation
postgres-main	postgres-main	postgres:15-alpine	PostgreSQL database
bucko-web-prod	bucko-web-prod	bucko-bucko-web	Static website (Astro)
adminer	adminer	adminer	Database admin UI
promtail	promtail	grafana/promtail:latest	Log shipping

Key Paths

Path	Purpose
/opt/docker/	All Docker projects root
/opt/docker/bucko/	Bucko website (Astro)
/opt/docker/docs/	Documentation site (Starlight)
/opt/docker/n8n/	n8n workflow automation
/opt/docker/postgres/	PostgreSQL configuration
/opt/docker/traefik/	Traefik reverse proxy
/home/samob/	User home, backup storage

Network Topology

                    ┌─────────────────┐
                    │    Traefik      │
                    │  (reverse proxy)│
                    │   :80, :443     │
                    └────────┬────────┘
                             │
                    ┌────────┴────────┐
                    │   proxy network │
                    │    (external)   │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        ▼                    ▼                    ▼
  ┌───────────┐       ┌───────────┐       ┌───────────┐
  │   docs    │       │    n8n    │       │bucko-web  │
  │  :4322    │       │   :5678   │       │  :4321    │
  └───────────┘       └─────┬─────┘       └───────────┘
                            │
                            ▼
                      ┌───────────┐
                      │ postgres  │
                      │  :5432    │
                      └───────────┘

All web services connect to the proxy Docker network. Traefik routes traffic based on Host headers.

DNS & Domains

Domain	Service	Container
bucko.smilepowered.org	Bucko website	bucko-web-prod
n8n.smilepowered.org	n8n workflows	n8n
docs.smilepowered.org	Documentation	docs
adm.smilepowered.org	Traefik dashboard	traefik

Credentials Locations

Service	Location	Notes
PostgreSQL	/opt/docker/postgres/compose.yaml	POSTGRES_PASSWORD
n8n database	/opt/docker/n8n/compose.yaml	DB_POSTGRESDB_PASSWORD
n8n encryption	/opt/docker/n8n/compose.yaml	N8N_ENCRYPTION_KEY - also in volume
Traefik	/opt/docker/traefik/compose.yaml	ACME email for Let’s Encrypt

Traefik Labels Pattern

To expose a service through Traefik, add these labels to compose.yaml:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.<name>.rule=Host(`<domain>`)"
  - "traefik.http.routers.<name>.entrypoints=websecure"
  - "traefik.http.routers.<name>.tls.certresolver=letsencrypt"
  - "traefik.http.services.<name>.loadbalancer.server.port=<internal_port>"

Common Commands

Container Management

# List all running containers
docker ps

# View container logs
docker logs <container_name>

# Follow logs in real-time
docker logs -f <container_name>

# Restart a service
cd /opt/docker/<service> && docker compose restart

# Rebuild and restart
cd /opt/docker/<service> && docker compose build && docker compose up -d

PostgreSQL

# List databases
docker exec postgres-main psql -U postgres -c "\l"

# Backup a database
docker exec postgres-main pg_dump -U <user> <database> > backup.sql

# Restore a database
cat backup.sql | docker exec -i postgres-main psql -U <user> -d <database>

Traefik

# Check Traefik logs for errors
docker logs traefik | grep -i error

# Verify container labels
docker inspect <container_name> --format '{{json .Config.Labels}}' | jq

# Check proxy network
docker network inspect proxy

Build Workflow

For services that require building (docs, bucko):

cd /opt/docker/<service>
./build.sh              # Build static files using Docker node:22-alpine
docker compose build    # Build container image
docker compose up -d    # Start container

Container Updates

Check if containers are outdated

Compare running container image IDs with local latest images:

# Get running container image ID
docker inspect <container_name> --format '{{.Image}}'

# Pull latest image
docker pull <image>:latest

# Compare with local images
docker images --format "table {{.Repository}}:{{.Tag}}\t{{.ID}}\t{{.CreatedAt}}" | grep <image>

Update a container

1. Pull the latest image:

   docker pull <image>:latest

2. Recreate the container:

   cd /opt/docker/<service>
   docker compose up -d

3. Verify update:

   docker inspect <container_name> --format '{{.Image}}'
   docker images --format "{{.ID}}" <image>:latest

Both IDs should match after update.

Current container versions

Container	Image	Update Command
traefik	traefik:latest	cd /opt/docker/traefik && docker compose up -d
n8n	n8nio/n8n:latest	cd /opt/docker/n8n && docker compose up -d
postgres-main	postgres:15-alpine	cd /opt/docker/postgres && docker compose up -d
adminer	adminer	cd /opt/docker/adminer && docker compose up -d
promtail	grafana/promtail:latest	cd /opt/docker/promtail && docker compose up -d

Backup Storage

Location	Contents
/home/samob/	Local backup copies (persistent)
/opt/docker/docs/public/downloads/	Downloadable backups via docs site

Troubleshooting

Container won’t start

docker logs <container_name>

Check for port conflicts, missing volumes, or configuration errors.

Traefik not routing to container

1. Verify container has correct labels
2. Verify container is on proxy network
3. Check Traefik logs: docker logs traefik

docker inspect <container_name> | grep -A 20 Labels
docker network inspect proxy

PostgreSQL connection refused

1. Check postgres is running: docker ps | grep postgres
2. Verify credentials in compose.yaml match
3. Test connection: docker exec postgres-main psql -U postgres -c "\l"

Permission denied in /opt/docker/

Files created by Docker may be owned by root. Use Docker to modify:

docker run --rm -v /opt/docker/<service>:/app -w /app node:22-alpine sh -c "rm -rf node_modules"

Related Guides

• Backup Static Astro Site
• Backup n8n with PostgreSQL
• Deploy Astro Starlight