Control Plane Deployment

The TurboPanel Control Plane is a self-hosted Docker image containing the frontend (Expo web build) and backend (Hono API with integrated agent functionality). It is the centralized management interface for Docker containers and infrastructure across multiple servers.

Overview

Purpose

• Centralized management for Docker containers and infrastructure
• REST API and frontend (Expo web) for management
• Integrated Docker management on the control plane server (self-hosted)
• WebSocket server for remote agents (self-hosted)

Relationship to Agent

In self-hosted mode, the control plane can manage local Docker directly without a separate agent on the same server. Additional servers use the agent image and connect via WebSocket. See Agent Setup for multi-server deployments.

Architecture

graph TD
    subgraph "Runtime"
        F[runtime image] --> G[Frontend dist]
        F --> H[Backend source]
        F --> I[Shared package]
        F --> J[Node.js · Port 18282]
    end

Deployment Models Comparison

This guide covers Self-Hosted deployment only. Edge mode uses a different control plane on the TurboPanel Edge platform.

Installation

Quick Start

curl -sSL https://start.trbp.nl/ | sh

The script pulls the image, creates directories, configures Docker Compose, and starts the container.

Manual Docker

1. docker pull turbopanel/turbopanel:latest
2. Run with port 18282, Docker socket mount, --restart unless-stopped
3. Access UI at http://your-server-ip:18282

docker run -d \
  --name turbopanel \
  --restart unless-stopped \
  -p 18282:18282 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  turbopanel/turbopanel:latest

Docker Compose

Save the following as docker-compose.yml in a directory of your choice (for example /opt/turbopanel/), then run docker compose up -d from that directory:

services:
  turbopanel:
    image: turbopanel/turbopanel:latest
    restart: unless-stopped
    ports:
      - "18282:18282"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

docker compose up -d

The install script writes an equivalent compose file and starts the container for you; the path it uses may vary by environment.

Multi-Server Setup

• Control plane server: Use this image only; integrated agent handles local Docker.
• Additional servers: Deploy the agent image; see Agent Setup.

Configuration

Environment Variables

Volume and Port

• Docker socket: -v /var/run/docker.sock:/var/run/docker.sock (required for local Docker management)
• Port: -p 18282:18282

API Endpoints

Communication Patterns

• Frontend–Backend: Same port; API at /api/v1; REST + WebSocket; token-based auth
• Integrated Agent: Direct Docker socket access on control plane server; no separate agent container
• WebSocket Server: ws://your-control-plane:18282/agent/connect; token auth; commands to agents, responses/logs back

Comparison: Control Plane vs Agent

Related Documentation

• Agent Setup — Multi-server deployments and agent configuration
• Security — Security best practices
• Deployment Troubleshooting — Common deployment issues