Self-hosting Periscope with Docker Compose¶

services:
  periscope:
    image: public.ecr.aws/x5l1y7s0/periscope:${PERISCOPE_VERSION:-latest}
    ports:
      # Host port to publish on the left; the app listens on 4000 inside.
      - "${PERISCOPE_PORT:-4000}:4000"
    environment:
      # The hostname browsers reach the app through. WebSocket connections
      # from any other origin are rejected, so set this to the real hostname
      # when deploying beyond localhost.
      PHX_HOST: ${PHX_HOST:-localhost}
      # The mounted inventory below.
      PERISCOPE_CONFIG_PATH: /etc/periscope/periscope.yaml
      # Global SSH credentials for the devices in periscope.yaml. Optional at
      # boot (an empty value counts as unset); command execution fails without
      # them unless every device names its own variables via username_env/
      # password_env — each variable named that way must also be passed here.
      DEVICE_USERNAME: ${DEVICE_USERNAME:-}
      DEVICE_PASSWORD: ${DEVICE_PASSWORD:-}
      # Optional: signs browser session cookies. When unset, a random key is
      # generated at boot (with a logged warning) and sessions reset on every
      # restart. Generate one with: openssl rand -base64 48
      SECRET_KEY_BASE: ${SECRET_KEY_BASE:-}
      # Optional tuning knobs — see "Environment variables" below:
      # UI_ENABLED: "false"             # API/MCP only, no web UI
      # LG_READ_TIMEOUT: "300"          # Netmiko read timeout, seconds
      # LG_MAX_CONCURRENT_EXECUTIONS: "10"
      # MCP_SERVER_TIMEOUT: "180"       # MCP transport timeout, seconds
    volumes:
      # Your device inventory. `create_host_path: false` makes a missing
      # ./periscope.yaml a clear Compose error instead of Docker silently
      # creating a directory in its place and failing at boot.
      - type: bind
        source: ./periscope.yaml
        target: /etc/periscope/periscope.yaml
        read_only: true
        bind:
          create_host_path: false
    restart: unless-stopped
    healthcheck:
      # python3 is already in the image (the diagnostic commands run under
      # it), so the check adds no packages. urlopen raises on any non-2xx/3xx
      # response, exiting non-zero and failing the check.
      test:
        [
          "CMD",
          "python3",
          "-c",
          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:4000/health', timeout=5)",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

# Human-facing name shown in the UI (navbar brand, browser-title suffix,
# splash page). Defaults to "Periscope" when omitted.
application_name: "Example Network Console"

# Optional: a URL for your documentation site, linked from the footer.
# Omit it and the footer shows only the product attribution.
documentation_url: "https://docs.example.net/periscope"

devices:
  - id: "core1.example.net"
    host: "192.0.2.10"
    platform: "cisco_xr"
    location: "Example City, ST"
    type: "Core Router"

  - id: "sw1.example.net"
    host: "192.0.2.20"
    platform: "arista_eos"
    location: "Example City, ST"
    type: "Switch"

  # A device can name its own credential environment variables instead of
  # the global DEVICE_USERNAME/DEVICE_PASSWORD. The value is the *name* of
  # an environment variable, never the secret itself. Any variable named
  # this way must also be passed into the container (add it under
  # `environment:` in compose.yaml), and boot aborts if it is unset.
  - id: "core1.partner.net"
    host: "192.0.2.30"
    platform: "cisco_xr"
    location: "Partner City, ST"
    type: "Core Router"
    username_env: "PARTNER_USERNAME"
    password_env: "PARTNER_PASSWORD"

services:
  periscope:
    image: public.ecr.aws/x5l1y7s0/periscope:${PERISCOPE_VERSION:-latest}
    # No `ports:` block — only Caddy is reachable from outside; it talks to
    # Periscope over the Compose network on port 4000.
    environment:
      # Must match the site address in the Caddyfile: Phoenix rejects
      # WebSocket connections from any other origin.
      PHX_HOST: ${PHX_HOST:?set PHX_HOST to the public hostname}
      PERISCOPE_CONFIG_PATH: /etc/periscope/periscope.yaml
      DEVICE_USERNAME: ${DEVICE_USERNAME:-}
      DEVICE_PASSWORD: ${DEVICE_PASSWORD:-}
      SECRET_KEY_BASE: ${SECRET_KEY_BASE:-}
    volumes:
      - type: bind
        source: ./periscope.yaml
        target: /etc/periscope/periscope.yaml
        read_only: true
        bind:
          create_host_path: false
    restart: unless-stopped
    healthcheck:
      test:
        [
          "CMD",
          "python3",
          "-c",
          "import urllib.request; urllib.request.urlopen('http://127.0.0.1:4000/health', timeout=5)",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

  caddy:
    image: caddy:2
    ports:
      - "80:80"
      - "443:443"
      # HTTP/3
      - "443:443/udp"
    environment:
      PHX_HOST: ${PHX_HOST:?set PHX_HOST to the public hostname}
    volumes:
      - type: bind
        source: ./Caddyfile
        target: /etc/caddy/Caddyfile
        read_only: true
        bind:
          create_host_path: false
      # Certificates and ACME account state — must persist across restarts,
      # or Caddy re-requests certificates and can hit Let's Encrypt rate
      # limits.
      - caddy_data:/data
      - caddy_config:/config
    restart: unless-stopped
    depends_on:
      periscope:
        condition: service_healthy

volumes:
  caddy_data:
  caddy_config: