webtop-manage
webtop-manage v1.0.0
/docs/getting-started/quickstart
Getting Started1 min webtop-manage v1.0.0

Quickstart & Deployment

Launch webtop-manage in under 60 seconds with Docker Compose or standalone binary.

Quickstart & Deployment

Get webtop-manage running on any machine in under 60 seconds.

🚀 1-Minute Launch via Docker Compose

1. Create docker-compose.yml

yaml
services:
  webtop-manage:
    # Option 1: Build directly from local source (zero publishing needed)
    build: .
    # Option 2: Or use a pre-built image
    # image: ghcr.io/mngdlnx/webtop-manage:latest
    container_name: webtop-manage
    restart: unless-stopped
    ports:
      # Strict 127.0.0.1 loopback binding for security
      - "127.0.0.1:8080:8080"
    volumes:
      # Docker daemon socket passthrough to manage sibling containers
      - /var/run/docker.sock:/var/run/docker.sock
      # Host root filesystem mount (read-only) for visual folder browsing
      - /:/host:ro
      # Optional: Custom Presets, Themes & Config files
      - ./presets.json:/app/presets.json:ro
      - ./themes.json:/app/themes.json:ro
      - ./config.json:/app/config.json:ro
    environment:
      - PORT=8080
      - BIND_HOST=0.0.0.0
      - APP_TITLE=webtop-manage
      - DEFAULT_INSTANCE_BIND_IP=127.0.0.1
      - DEFAULT_NETWORK=webtop-net
      - DEFAULT_TZ=Etc/UTC
      - DEFAULT_KEYBOARD=en-us-qwerty
      - DEFAULT_SHM_SIZE_MB=1024
      - BASE_PORT=3000
      - DEFAULT_EGRESS_POLICY=full
    networks:
      - webtop-net

networks:
  webtop-net:
    name: webtop-net
    driver: bridge

2. Start the Service

bash
docker compose up -d

3. Open the Dashboard

Open your browser and navigate to:

text
http://127.0.0.1:8080

!TIPZero-Trust Guarantee: Because the compose file binds to 127.0.0.1:8080:8080, your workstation manager is completely unreachable from the local Wi-Fi or public internet.

💻 Running as a Native Binary (Standalone)

You can also run webtop-manage directly on Linux, macOS, or Windows without containerizing the manager:

bash
# Clone repository
git clone https://github.com/mngdlnx/webtop-manage.git
cd webtop-manage

# Build static binary with embedded web assets
go build -ldflags="-s -w" -o webtop-manage ./cmd/webtop-manage

# Run daemon (Connects automatically to local Docker engine)
./webtop-manage

Docker Daemon Socket Auto-Detection

  • Linux: /var/run/docker.sock
  • macOS: ~/.docker/run/docker.sock or /var/run/docker.sock
  • Windows: npipe:////./pipe/docker_engine
  • Custom Engine: Pass DOCKER_HOST=tcp://remote-docker-host:2375 or specify in config.json.

🌐 Deploying Behind Reverse Proxies

To expose webtop-manage over secure HTTPS using Cloudflare Tunnels, Tailscale Funnel, Caddy, or Nginx:

  • WebSocket Terminal: The Go server accepts connections matching r.Host, so proxied WebSocket connections on /api/instances/{id}/terminal work out of the box.
  • Caddy Example:
    caddyfile
    webtop.internal.domain {
    reverse_proxy 127.0.0.1:8080
}
  • Nginx Example:
    nginx
    location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}