> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pangolin.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Compose

> Deploy Pangolin manually using Docker Compose without the automated installer

<div id="pangolin-toc-cta" className="pangolin-toc-cta-source">
  <Card title="Try free on Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup" arrow="true" cta="Sign up free">
    Fastest way to get started with Pangolin using the hosted control plane. No credit card required.
  </Card>
</div>

This guide walks you through setting up Pangolin manually using Docker Compose without the automated installer. This approach gives you full control over the configuration and deployment process.

This guide assumes you already have a Linux server with Docker and Docker Compose installed. If you don't, please refer to the [official Docker documentation](https://docs.docker.com/get-docker/) for installation instructions. You must also have root access to the server.

## Prerequisites

Checkout the [quick install guide](/self-host/quick-install) for more info regarding what is needed before you install Pangolin.

## File Structure

Create the following directory structure for your Pangolin deployment:

```
.
├── config/
│   ├── config.yml (*)
│   ├── db/
│   │   └── db.sqlite
│   ├── key
│   ├── letsencrypt/
│   │   └── acme.json
│   ├── logs/
│   └── traefik/
│       ├── traefik_config.yml (*)
│       └── dynamic_config.yml (*)
└── docker-compose.yml (*)
```

<Info>
  Files marked with `(*)` must be created manually. Volumes and other files are generated automatically by the services.
</Info>

<AccordionGroup>
  <Accordion title="Configuration Files">
    **`config/config.yml`**: Main Pangolin configuration file

    * Contains all Pangolin settings and options
    * See [Configuration Guide](/self-host/advanced/config-file) for details

    **`config/traefik/traefik_config.yml`**: Traefik static configuration

    * Global Traefik settings and entry points
    * SSL certificate resolver configuration

    **`config/traefik/dynamic_config.yml`**: Traefik dynamic configuration

    * HTTP routers and services for Pangolin
    * Load balancer and middleware configuration
  </Accordion>

  <Accordion title="Generated Files">
    **`config/db/db.sqlite`**: SQLite database file

    * Created automatically on first startup
    * Contains all Pangolin data and settings

    **`config/key`**: Private key file

    * Generated by Gerbil service
    * Used for WireGuard tunnel encryption

    **`config/letsencrypt/acme.json`**: SSL certificate storage

    * Managed by Traefik
    * Contains Let's Encrypt certificates
  </Accordion>

  <Accordion title="Docker Files">
    **`docker-compose.yml`**: Service definitions

    * Defines Pangolin, Gerbil, and Traefik services
    * Network configuration and volume mounts
    * Health checks and dependencies
  </Accordion>
</AccordionGroup>

<Steps>
  <Step title="Create configuration directory">
    ```bash theme={"dark"}
    mkdir -p config/traefik config/db config/letsencrypt config/logs
    ```
  </Step>

  <Step title="Create configuration files">
    Create the main configuration files (see below):

    * `docker-compose.yml` (in project root)
    * `config/traefik/traefik_config.yml`
    * `config/traefik/dynamic_config.yml`
    * `config/config.yml`
  </Step>

  <Step title="Update domain and email">
    Edit the configuration files to replace:

    * `pangolin.example.com` with your actual domain
    * `admin@example.com` with your email address

    <Warning>
      Ensure your domain DNS is properly configured to point to your server's IP address.
    </Warning>
  </Step>
</Steps>

## Starting the Stack

<Steps>
  <Step title="Start the services">
    ```bash theme={"dark"}
    sudo docker compose up -d
    ```
  </Step>

  <Step title="Monitor startup">
    ```bash theme={"dark"}
    sudo docker compose logs -f
    ```
  </Step>

  <Step title="Verify services">
    ```bash theme={"dark"}
    sudo docker compose ps
    ```

    All services should show "Up" status after a few minutes.
  </Step>

  <Step title="Access the dashboard">
    Navigate to `https://your-domain.com/auth/initial-setup` to complete the initial setup.

    <Check>
      The dashboard should load with SSL certificate automatically configured.
    </Check>
  </Step>
</Steps>

## Docker Compose Configuration

Create `docker-compose.yml` in your project root:

```yaml title="docker-compose.yml" theme={"dark"}
name: pangolin
services:
  pangolin:
    image: docker.io/fosrl/pangolin:latest # https://github.com/fosrl/pangolin/releases
    container_name: pangolin
    restart: unless-stopped
    volumes:
      - ./config:/app/config
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"]
      interval: "10s"
      timeout: "10s"
      retries: 15

  gerbil:
    image: docker.io/fosrl/gerbil:latest # https://github.com/fosrl/gerbil/releases
    container_name: gerbil
    restart: unless-stopped
    depends_on:
      pangolin:
        condition: service_healthy
    command:
      - --reachableAt=http://gerbil:3004
      - --generateAndSaveKeyTo=/var/config/key
      - --remoteConfig=http://pangolin:3001/api/v1/
    volumes:
      - ./config/:/var/config
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    ports:
      - 51820:51820/udp
      - 21820:21820/udp
      - 443:443
      - 80:80

  traefik:
    image: docker.io/traefik:v3.6
    container_name: traefik
    restart: unless-stopped

    network_mode: service:gerbil # Ports appear on the gerbil service

    depends_on:
      pangolin:
        condition: service_healthy
    command:
      - --configFile=/etc/traefik/traefik_config.yml
    volumes:
      - ./config/traefik:/etc/traefik:ro # Volume to store the Traefik configuration
      - ./config/letsencrypt:/letsencrypt # Volume to store the Let's Encrypt certificates
      - ./config/traefik/logs:/var/log/traefik # Volume to store Traefik logs

networks:
  default:
    driver: bridge
    name: pangolin
    #enable_ipv6: true # activate if your system supports IPv6
```

## Traefik Static Configuration

Create `config/traefik/traefik_config.yml`:

```yaml title="config/traefik/traefik_config.yml" theme={"dark"}
api:
  insecure: true
  dashboard: true

providers:
  http:
    endpoint: "http://pangolin:3001/api/v1/traefik-config"
    pollInterval: "5s"
  file:
    filename: "/etc/traefik/dynamic_config.yml"

experimental:
  plugins:
    badger:
      moduleName: "github.com/fosrl/badger"
      version: "v1.3.1"

log:
  level: "INFO"
  format: "common"
  maxSize: 100
  maxBackups: 3
  maxAge: 3
  compress: true

certificatesResolvers:
  letsencrypt:
    acme:
      httpChallenge:
        entryPoint: web
      email: "admin@example.com" # REPLACE WITH YOUR EMAIL
      storage: "/letsencrypt/acme.json"
      caServer: "https://acme-v02.api.letsencrypt.org/directory"

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
    transport:
      respondingTimeouts:
        readTimeout: "30m"
    http:
      tls:
        certResolver: "letsencrypt"
      encodedCharacters:
        allowEncodedSlash: true
        allowEncodedQuestionMark: true

serversTransport:
  insecureSkipVerify: true

ping:
  entryPoint: "web"
```

## Traefik Dynamic Configuration

Create `config/traefik/dynamic_config.yml`:

```yaml title="config/traefik/dynamic_config.yml" theme={"dark"}
http:
  middlewares:
    badger:
      plugin:
        badger:
          disableForwardAuth: true
    redirect-to-https:
      redirectScheme:
        scheme: https

  routers:
    # HTTP to HTTPS redirect router
    main-app-router-redirect:
      rule: "Host(`pangolin.example.com`)" # REPLACE WITH YOUR DOMAIN
      service: next-service
      entryPoints:
        - web
      middlewares:
        - redirect-to-https
        - badger

    # Next.js router (handles everything except API and WebSocket paths)
    next-router:
      rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)" # REPLACE WITH YOUR DOMAIN
      service: next-service
      entryPoints:
        - websecure
      middlewares:
        - badger
      tls:
        certResolver: letsencrypt

    # API router (handles /api/v1 paths)
    api-router:
      rule: "Host(`pangolin.example.com`) && PathPrefix(`/api/v1`)" # REPLACE WITH YOUR DOMAIN
      service: api-service
      entryPoints:
        - websecure
      middlewares:
        - badger
      tls:
        certResolver: letsencrypt

    # WebSocket router
    ws-router:
      rule: "Host(`pangolin.example.com`)" # REPLACE WITH YOUR DOMAIN
      service: api-service
      entryPoints:
        - websecure
      middlewares:
        - badger
      tls:
        certResolver: letsencrypt

  services:
    next-service:
      loadBalancer:
        servers:
          - url: "http://pangolin:3002"  # Next.js server

    api-service:
      loadBalancer:
        servers:
          - url: "http://pangolin:3000"  # API/WebSocket server

tcp:
  serversTransports:
    pp-transport-v1:
      proxyProtocol:
        version: 1
    pp-transport-v2:
      proxyProtocol:
        version: 2
```

## Pangolin Configuration

Create `config/config.yml` with your Pangolin settings. See the [configuration guide](/self-host/advanced/config-file) for detailed options and examples.