81 lines
4.6 KiB
Markdown
81 lines
4.6 KiB
Markdown
# 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:
|
|
```bash
|
|
sudo bash create_webtop_folders.sh
|
|
```
|
|
- [ ] **Action**: Apply the folder creation and ownership settings:
|
|
```bash
|
|
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!
|