Diagnostics & Troubleshooting

Common troubleshooting steps and solutions for running containerized Linux desktops with webtop-manage.

⚡ 1. Port Conflicts & Auto-Allocation

Problem

Attempting to launch an instance results in Port conflict on 3000 or bind: address already in use.

Solution

• Automated Scan: In the Custom Blueprint wizard or via the API, click the Scan Next Port icon (🔄). webtop-manage verifies port availability by attempting test socket binds.
• Custom Base Port: If ports 3000-3050 are used by other local services (e.g. Grafana, React dev servers), configure BASE_PORT=4000 in your environment or config.json.

🔌 2. Docker Daemon Socket Permissions

Problem

Fatal: Failed to connect to Docker daemon: permission denied or failed to ping docker daemon.

Solution

Linux Host

Ensure your local user belongs to the docker group, or verify that /var/run/docker.sock is accessible:

# Add current user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Or adjust socket permissions (development only)
sudo chmod 666 /var/run/docker.sock

Windows Host (Docker Desktop)

• Make sure Docker Desktop is running.
• webtop-manage automatically falls back between npipe:////./pipe/docker_engine and standard environment settings.
• In WSL2, enable Docker integration for your distro in Docker Desktop Settings $\rightarrow$ Resources $\rightarrow$ WSL Integration.

macOS Host

webtop-manage automatically probes both /var/run/docker.sock and ~/.docker/run/docker.sock.

🧠 3. Shared Memory (/dev/shm) Sizing for Browsers & IDEs

Problem

Chromium, Firefox, VS Code, or Electron apps crash inside the desktop container with SIGSEGV, SIGBUS, or Aw, Snap!.

Cause

Docker's standard default shared memory is only 64 MB, which is insufficient for modern multi-tab browser render trees and GPU compositing.

Solution

webtop-manage automatically sets --shm-size based on preset recommendations:

🎮 4. GPU Hardware Acceleration Passthrough

Intel QuickSync / Integrated GPU (/dev/dri)

When Enable Hardware Acceleration is checked, webtop-manage passes /dev/dri render nodes with rwm permissions:

devices:
  - /dev/dri:/dev/dri

NVIDIA Discrete GPUs

Install the NVIDIA Container Toolkit on your host. If using Docker Compose:

deploy:
  resources:
    reservations:
      devices:
        - driver: nvidia
          count: all
          capabilities: [gpu]

📋 5. Common Error Messages & Remedies