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]:3000.

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.