VPS Infrastructure Architecture

This diagram illustrates the consolidated Docker architecture on the Strato VPS, managed via the central /opt/cfs-infra/docker-compose.yml.

All web services are exposed through the secure Traefik entrypoint. Internal services like the Database and Ollama communicate securely over the internal Docker network without exposure to the internet.

graph TD
    classDef External fill:#f9f9f9,stroke:#333,stroke-width:2px;
    classDef Proxy fill:#e1d5e7,stroke:#9673a6,stroke-width:2px;
    classDef Service fill:#d5e8d4,stroke:#82b366,stroke-width:2px;
    classDef Internal fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px;

    Internet((Internet)) -->|HTTPS| Traefik[Traefik Proxy]
    class Internet External

    Traefik -->|ag-ls...| Antigravity(Antigravity AI Desktop)
    Traefik -->|portainer-ls...| Portainer(Portainer)
    Traefik -->|ai-ls...| OpenWebUI(Open-WebUI)

    class Traefik Proxy
    class Antigravity,Portainer,OpenWebUI Service

    subgraph Internal Network
        cfs-db-local[(cfs-db-local: MariaDB Port 3307)]
        cfs-database-staging[(cfs-database-staging: MariaDB Port 3308)]
        cfs-database-prod[(cfs-database-prod: MariaDB Port 3306)]
        redis-cache[(redis-cache: Redis)]
        Ollama((Ollama Local AI))
        class cfs-db-local,cfs-database-staging,cfs-database-prod,redis-cache,Ollama Internal
    end

    OpenWebUI -.->|Internal connection| Ollama
    OpenWebUI -.->|Internal connection| redis-cache
    Portainer -.->|Read-only socket| DockerDaemon(Docker Daemon)

    subgraph Persistence Layer
        VolumeData[/home/kasm-user/data]
        VolumeData -->|.gemini| Antigravity
        VolumeData -->|.npm / .nvm| Antigravity
        VolumeData -->|.vscode| Antigravity
    end

Antigravity Persistence System

To ensure high-availability and prevent data loss during container upgrades, a robust persistence layer is managed via startup.sh. This ensures the Antigravity IDE environment is fully restored including user settings and AI state.

• Unified Persistence Layout:

  • ~/.gemini: Agent history, skills, and knowledge base.
  • ~/.config/xfce4: Desktop layout, themes, and panel shortcuts.
  • ~/.config/Nextcloud: Active sync sessions and account settings.
  • ~/Nextcloud: Local copy of the synchronized document environment.
  • ~/.vscode: Extensions and user settings.

• Developer Environment: Terminal configs (.bashrc) and Node.js environments (.nvm, .npm) are persisted to maintain installed CLI tools and workspace state.

Superpowers Workflows Integration

The infrastructure is tightly integrated with the Superpowers ecosystem in the SERVER-MANAGER orchestrator:

• Plan-First Execution: All infrastructure changes must be planned via /superpowers-write-plan and verified against these architectural standards.
• Verification Protocol: The orchestrator verifies these persistence rules are intact before any docs(encyclopedia): synchronization.

Remote Execution Protocol

The VPS infrastructure is managed and orchestrated from the local development system via Unix-native Bash scripts:

• Primary Interface: ./platform/linux/vps-connect.sh "<command>" or other scripts in ./platform/linux/ (e.g., vps-status.sh, backup-tools.sh, vps-cleanup.sh)
• Authentication: SSH identity key ~/.ssh/id_ed25519_antigravity
• Environment: Native Linux shell with standard utilities
• Logging: Console output with exit code propagation

Linux-First / VPS-First Development

The SERVER-MANAGER operates primarily from a Linux environment:

• Local Development: Windsurf/VS Code on Linux (CFS-HOME-2-LINUX)
• Remote Management: Bash-based SSH orchestration and deployment tools
• Documentation: VitePress with native Node.js/npm commands
• Version Control: Git with Unix-native workflows

Antigravity IDE Emergency Mode

In special cases, the SERVER-MANAGER is run directly within the cfs-antigravity-ide container on the VPS to troubleshoot specific platform issues or run emergency repairs. This is made possible by the privileged credentials of the Server-Manager and is deliberately configured to provide double security and system flexibility.