How Disco Works

Disco is designed to give you a “Platform-as-a-Service” experience while running entirely on your own infrastructure. It achieves this by orchestrating standard, battle-tested open-source technologies.

Architecture Overview

Disco follows a split architecture between the Data Plane (your server) and the Control Plane (the Dashboard or CLI).

• The Data Plane (Your Server): This is where your code runs, your database lives, and your user traffic is handled. You own this infrastructure completely.
• The Control Plane (Dashboard / CLI): These are interfaces that send commands to your server’s API. They authenticate using API keys, allowing you and your team to manage deployments without SSH.

Crucially, your application traffic never passes through Disco’s servers. Webhooks from GitHub go directly to your server, and user requests go directly to your server.

---
config:
  layout: elk
---
flowchart TB
 subgraph subGraph0["Project A (Web App)"]
        App1["Web Container"]
        Worker1["Worker Container"]
        Volume1["Persistent Volume"]
  end
 subgraph subGraph1["Your Server"]
        Caddy["Caddy
        (Reverse Proxy + SSL)"]
        Daemon["Disco Daemon
        (API & Controller)"]
        Swarm["Docker Swarm"]
        subGraph0
  end
 subgraph subGraph2["External World"]
        GitHub["GitHub
        (Source Code)"]
        User["User / Internet"]
        DashboardCLI["Web UI and CLI"]
  end
    GitHub -- Webhooks (Push) --> Caddy
    DashboardCLI -- API Commands --> Caddy
    User -- HTTPS Requests --> Caddy
    Caddy -- Routes API to --> Daemon
    Caddy -- Routes Web to --> App1
    Daemon -- Configures --> Caddy
    Daemon -- Orchestrates --> Swarm
    Swarm -- Runs --> App1 & Worker1
    App1 -- Mounts --> Volume1

---

Core Components

1. The Daemon

The Disco Daemon is a lightweight agent that runs on your server. It exposes a secure REST API that the Dashboard and CLI use to manage your projects.

• GitHub Integration: Unlike many PaaS providers, the GitHub App is installed directly on your server. This means GitHub sends webhooks straight to your machine, not to a central Disco cloud service.
• Team Access: The Daemon manages API keys, allowing multiple team members (via CLI or Dashboard) to deploy and manage the server securely.

2. Docker Swarm

We use Docker Swarm (not Kubernetes) for orchestration. Swarm is built into Docker and provides the perfect balance of simplicity and power for single-server or small-cluster setups.

• Zero-Downtime: Swarm handles rolling updates. When you deploy, it starts the new container, waits for it to be healthy, and only then switches traffic and stops the old one.
• Scalability: You can scale services horizontally (e.g., disco scale web=3) instantly.

3. Caddy (The Router)

Caddy sits at the edge of your server, handling all incoming HTTP/HTTPS traffic.

• SSL Termination: Caddy automatically provisions and renews Let’s Encrypt SSL certificates for every domain you add.
• Dynamic Routing: The Daemon dynamically updates Caddy’s configuration to route traffic to your running containers based on domain names.

---

The Deployment Flow

What happens when you git push?

1. Webhook: GitHub sends a webhook directly to your server’s Daemon.
2. Build: The Daemon pulls your code and builds a Docker image (using your Dockerfile).
3. Health Check: The Daemon starts a new container from that image. It waits for your app to listen on its configured port (e.g., 3000).
4. Switch: Once healthy, Caddy is updated to point traffic to the new container.
5. Cleanup: The old container is stopped and removed.

This ensures that if a deployment fails (e.g., your code crashes on startup), the old version remains live and no traffic is lost.

Key Concepts

• Project: Represents a single application (e.g., “My Blog”). A project maps to a GitHub repository. Your server can host unlimited projects.
• Service: A process running within a project. A typical web app might have a web service (the HTTP server) and a worker service (background jobs).
• Volume: Persistent storage. Since containers are ephemeral (they are destroyed on every deploy), any data you want to keep (like SQLite databases or user uploads) must be stored in a Volume.