ADR 0002: VPS Infrastructure Consolidation

Status

Accepted

Context

The previous VPS infrastructure consisted of multiple independent docker-compose projects scattered across the /opt/ directory (e.g., /opt/traefik, /opt/n8n, /opt/antigravity). This lead to several problems:

1. Fragmentation: No single overview of all running services, making it easy to overlook a component.
2. Security:
   • The docker.sock was mounted rw into the antigravity container, giving the AI desktop instance effective root control over the host.
   • The MariaDB port 3306 was exposed to the public internet, creating a critical security risk.
3. Instability: The n8n service was crashing in a restart loop due to incorrect directory ownership on the host.
4. Missing Health Checks: Containers lacked health check definitions, making it harder to determine their actual operational state automatically.

Decision

We decided to replace the fragmented setup with a single source of truth: a central docker-compose.yml file located at /opt/cfs-infra/docker-compose.yml. This file defines every service, network, and volume in one place.

Specifically, the following changes were made:

1. Centralization: All services (Traefik, MariaDB, Antigravity, Portainer, n8n, Ollama, Open-WebUI) are defined in one compose file and share a single .env file for secrets.
2. Security Enhancements:
   • Removed the docker.sock mount from the antigravity container. It now operates as a pure VNC desktop instance. Docker management is handled via portainer.
   • Removed the external port mapping for MariaDB. The database is now only accessible via the internal Docker network.
3. Stability Fixes: The ownership of /opt/stacks/n8n/data was fixed (chown -R 1000:1000), allowing n8n to run stably without crashing.
4. Resiliency: Added Docker health checks for cfs-database, n8n, and open-webui.

Consequences

• Positive: Improved security, easier management, and clear visibility of all running services. The AI desktop operates safely without host privileges.
• Negative/Trade-offs: A single compose file implies that bringing down the stack affects all services simultaneously, although individual services can still be managed (e.g., docker compose stop svc). Any changes to infrastructure now require modifying the central file.