# How Disco Works

> Understand the architecture behind your private PaaS.

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.