# Webtop Linux Desktop

> Full Linux desktop environment accessible via web browser with persistent storage.

- Category: Development Tools
- Difficulty: beginner
- Components: webtop, nginx
- Tags: webtop, linux, desktop, browser, remote
- Source: https://docker.recipes/development/webtop-linux-desktop

## Overview

LinuxServer.io's Webtop is a revolutionary container solution that delivers full Linux desktop environments directly through web browsers, eliminating the need for traditional VNC clients or remote desktop software. Built on Docker technology, Webtop transforms how users access Linux desktops by providing complete KDE, XFCE, or other desktop environments that run entirely within containers and stream to browsers via noVNC and web technologies. This approach makes Linux desktops instantly accessible from any device with a web browser, regardless of the client operating system.

This stack combines Webtop's browser-based Linux desktop capabilities with NGINX's high-performance web serving to create a production-grade remote desktop solution. NGINX acts as a reverse proxy and load balancer, handling SSL termination, compression, and optimizing the web-based desktop streaming performance. The integration allows for advanced features like custom domain routing, SSL certificate management, and improved connection handling for the desktop streaming protocols.

Development teams, system administrators managing headless servers, educational institutions providing lab environments, and organizations requiring secure remote access to Linux environments will find this stack invaluable. The combination offers enterprise-grade remote desktop access without the complexity of traditional VDI solutions, making it perfect for DevOps workflows, remote development environments, and secure browser-based access to Linux tools and applications.

## Features

- Complete KDE Plasma desktop environment accessible through any modern web browser
- Multiple Linux distribution bases including Ubuntu, Alpine, and Fedora variants
- Persistent user home directory and application data across container restarts
- NGINX reverse proxy with WebSocket support for optimized desktop streaming
- Built-in noVNC web client eliminating need for separate VNC viewers
- Configurable desktop resolution and display settings via environment variables
- Pre-installed development tools and applications in the containerized desktop
- NGINX SSL/TLS termination for secure HTTPS access to the desktop environment

## Use cases

- Remote development environments for distributed software teams
- Secure Linux desktop access for employees working from personal devices
- Educational computer labs accessible from student personal computers
- DevOps administration interfaces for managing servers and infrastructure
- Isolated testing environments for software development and QA
- Temporary Linux desktop instances for training and demonstrations
- Browser-based access to Linux-specific tools and applications on Windows/Mac networks

## Prerequisites

- Minimum 2GB RAM for basic KDE desktop functionality, 4GB+ recommended
- Docker host with at least 10GB free disk space for desktop environment
- Ports 80, 443, and 3000 available on the Docker host
- Modern web browser with WebSocket and HTML5 support
- Basic understanding of Linux desktop environments and file permissions
- Valid TZ environment variable configured for proper timezone display

## docker-compose.yml

```yaml
services:
  webtop:
    image: lscr.io/linuxserver/webtop:ubuntu-kde
    environment:
      PUID: 1000
      PGID: 1000
      TZ: ${TZ}
      SUBFOLDER: /
    ports:
      - "3000:3000"
    volumes:
      - webtop_config:/config
    shm_size: "1gb"
    networks:
      - webtop-net
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - webtop
    networks:
      - webtop-net
    restart: unless-stopped

volumes:
  webtop_config:

networks:
  webtop-net:
    driver: bridge
```

## .env

```bash
# Timezone
TZ=UTC

# User/Group IDs
PUID=1000
PGID=1000
```

## Usage notes

- Desktop at http://localhost:3000
- Full KDE desktop environment
- Persistent home directory
- Available flavors: alpine, ubuntu, fedora

## Troubleshooting

- Desktop appears blank or unresponsive: Increase shm_size to 2gb or higher for graphics-intensive applications
- Permission denied errors in desktop applications: Verify PUID and PGID match your host user's ID values
- Connection refused on port 3000: Check if webtop container started successfully and firewall allows the port
- NGINX 502 Bad Gateway errors: Ensure webtop service is running and accessible on the webtop-net network
- Desktop performance is slow: Reduce browser zoom level and close unnecessary tabs consuming memory
- Applications won't save files: Verify the webtop_config volume has proper write permissions

