portioner/webtop/SETUP.md

Service Setup Guide: Webtop

Webtop provides a full Linux desktop environment (Ubuntu XFCE) directly in your web browser.

1. Pre-Setup (Manual)

Create Service User

• Manual: Create a local user named svc-webtop in Synology DSM (Control Panel > User & Group).
• Manual: Give this user read/write access to the docker shared folder.

Get User IDs

• Manual: SSH into your NAS and run sudo synouser --get svc-webtop.
• Confirmed IDs: Locate the User ID (PUID) and Group ID (PGID).
• Action: Open create_webtop_folders.sh and update the USER_ID="[PUID]:[PGID]" line.
• Action: Open stack.env and update the PUID and PGID variables.

2. Infrastructure Setup

Run Setup Script

• Action: Run the setup script in Dry-Run mode to verify changes:

  sudo bash create_webtop_folders.sh
  

• Action: Apply the folder creation and ownership settings:

  sudo bash create_webtop_folders.sh --run
  

• What it does:
  • Creates /volume1/docker/webtop/config which acts as the persistent home directory (/config) for your virtual desktop.
  • Sets ownership securely to the svc-webtop user so the container process can write to it.

3. Portainer Deployment

Environment Variables

• Action: Review stack.env. You can customize the browser tab name by editing TITLE.

Deploy Stack

• Action: Create a new stack named webtop-stack.
• Action: Upload or paste the environment variables from stack.env.
• Action: Paste the content of docker-compose.portainer.yml and deploy.
• Verification: Access the Webtop desktop interface at http://[NAS_IP]:3030.

4. Post-Setup Notes

1. Persistent Data: Everything saved strictly within the virtual ~ or /config directory is retained. If you want to access your real NAS files (like your ebooks or movies) from inside this desktop, you can uncomment and map /volume1/media in the docker-compose.portainer.yml file.
2. Security Opt: The seccomp:unconfined flag is enabled. This is required to run multi-process modern browsers (like Google Chrome or Firefox) natively inside the container without crashing.
3. Execution User: Unlike some custom containers, Linuxserver.io images (like Webtop) handle user switching natively inside the container. Do not forcefully apply the user: directive in Docker Compose, as it will break the container's boot process which relies on root purely to set permissions before downgrading to the PUID/PGID.

5. Security: Cloudflare Zero Trust (Required for Internet Exposure)

Caution

The Webtop container gives anyone who accesses it a passwordless root terminal (sudo) within the container. You must not expose this to the public internet (e.g., via Cloudflare Tunnel) without an authentication layer in front of it.

If you are routing webtop.chengs.uk through a Cloudflare Tunnel, follow these steps to secure it with Cloudflare Access. CRITICAL: Do this BEFORE adding the public hostname to your Cloudflare Tunnel to ensure zero exposure time.

1. Go to your Cloudflare Zero Trust Dashboard (one.dash.cloudflare.com).
2. Navigate to Access -> Applications and click Add an Application.
3. Choose Self-hosted.
4. Application Configuration:
   • Application Name: Webtop NAS
   • Subdomain: webtop
   • Domain: chengs.uk
5. Add a Policy:
   • Policy Name: Allow Admin Only
   • Action: Allow
   • Include: Select Emails and type your personal email address (e.g., your-email@gmail.com).
6. Save the application.

Now, when you visit webtop.chengs.uk, you will be intercepted by a Cloudflare login screen. Cloudflare will email you a one-time pin, verifying your identity before you are allowed to reach the Webtop desktop.

6. Access: Connect the Cloudflare Tunnel

Now that the door is locked via the Access Policy, you can safely create the DNS record and route traffic to your NAS.

1. In the Cloudflare Zero Trust Dashboard, go to Networks -> Tunnels.
2. Click on your active NAS tunnel (e.g., nas-tunnel) and select Configure.
3. Go to the Public Hostname tab.
4. Click Add a public hostname.
5. Configuration:
   • Subdomain: webtop
   • Domain: chengs.uk
   • Service Type: HTTP (The Cloudflare daemon handles the external HTTPS encryption).
   • Service URL: [YOUR_NAS_LOCAL_IP]:3030 (e.g., 192.168.1.100:3030).
6. Click Save hostname.

Cloudflare will automatically create the DNS record for webtop.chengs.uk. You can now navigate to that URL from anywhere in the world to securely access your personal cloud desktop!