Setting up SDE vApps (one-click apps)

1. What you're setting up

SDE vApps is an optional add-on to an SDE Remote deployment, in its own GL unit (sde-vapps) with its own admin page at https://<portal>/sde-vapps/. A vApp is one app published as a tile. There are five kinds:

How it fits together. Each vApp is one ordinary RDP connection in Guacamole, which sde-vapps writes and grants to the vApp's groups and users. The gateway launches it like any other connection (natively from SDE Remote), and Guacamole opens it in a browser tab. sde-vapps is not in the launch path: if it's stopped, published apps keep working; only creating and changing them needs it.

How a web vApp is built. On "Create", sde-vapps:

1. clones the web template on the node with the most free memory into a container (CT 7000–7099);
2. sizes it, attaches it to the chosen bridge (DHCP) and sets its DNS and inbound firewall;
3. starts it and connects over SSH with its own key;
4. points the browser at the target, allows only the target in the browser and the container's outbound firewall, and sets up sign-in (a kiosk account, or joining AD);
5. publishes the Guacamole connection and grants it. A tile appears about a minute after Create.

2. Before you start

3. Proxmox token

sde-vapps has its own token, independent of SDE VDI (a site can have either or both). Copy scripts/vapps/pve-bootstrap-sde-vapps.sh to any node and run it once as root:

bash pve-bootstrap-sde-vapps.sh            # creates everything, prints the env lines
bash pve-bootstrap-sde-vapps.sh --check    # later: OK / FIX per item, changes nothing

It also installs a small timer on that node, sde-vapps-fuse.timer, that turns on file transfer for every template and host as they're built (section 6.1). Nothing to run again later.

It creates the pool sde-vapps, the role SDEVAPPS (container and storage privileges only), the user sde-vapps@pve, the token sde-vapps@pve!vapps (secret shown once) and the ACLs on the pool, the container storages and the SDN zone. --rotate-token replaces the token.

pveum pool add sde-vapps --comment "SDE vApps web containers and their template"
pveum role add SDEVAPPS --privs "VM.Allocate VM.Clone VM.Audit VM.PowerMgmt VM.Config.Options VM.Config.Network VM.Config.Memory VM.Config.CPU VM.Config.Disk Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit"
pveum user add sde-vapps@pve
pveum user token add sde-vapps@pve vapps --privsep 0
pveum acl modify /                 --users sde-vapps@pve --roles PVEAuditor
pveum acl modify /pool/sde-vapps   --users sde-vapps@pve --roles SDEVAPPS
pveum acl modify /storage/<each>  --users sde-vapps@pve --roles SDEVAPPS     # container + image storages
pveum acl modify /sdn/zones/localnetwork --users sde-vapps@pve --roles PVESDNUser

4. Active Directory (optional)

Only needed for web vApps where users sign in with their own account (SSO). Kiosk vApps (the default for legacy content) need none of this. On a DC, in an elevated PowerShell:

powershell -ExecutionPolicy Bypass -File ad-bootstrap-sde-vdi.ps1 -For vapps

It creates OU=apps under OU=sde, the join account sde-vapps-join (random password, never expires, not a Domain Admin: delegated to create, join and delete computers in that OU only, including the attributes Linux's adcli writes), and the group sde-apps-users. It prints the SDE_VAPPS_AD_* and SDE_VAPPS_DNS* lines for the next step. -Check reports only.

5. Deploy the sde-vapps unit

On the gateway host, from the SDE Remote deployment files, one interactive run installs and wires everything:

sudo deploy/glitch-units/deploy-sde-vapps.sh --wire --dry-run    # shows what it would change
sudo deploy/glitch-units/deploy-sde-vapps.sh --wire
sudo deploy/glitch-units/deploy-sde-vapps.sh --check             # any time: the tests only

Paste the lines from sections 3 and 4 when asked. It defaults the Guacamole URL and gua_srv password from the gateway's settings, generates the shared secret, writes the unit's environment (backing up any file it changes), adds the /sde-vapps/ route to sde-nginx, restarts with confirmation, and tests that the admin page answers and that /sde-vapps/v1/ and /sde-vapps/host/ are refused through the portal.

State lives in /var/glitch-units/sde-vapps/data/state: the vApps, kiosk passwords, sde-vapps' SSH key, and a daily copy of the state (14 kept). It must persist; include it in the host backup.

6. Build the templates

Every host sde-vapps builds is cloned from a template on its node: the Web browsers template (Chromium and Pale Moon, for every web vApp) and one for each catalogue app you use. Open https://<portal>/sde-vapps/ (sign in as a Guacamole administrator) → Hosts → Templates, choose Web browsers and a node (or Best node), and click Build. Catalogue apps' templates are built the same way, or from their card on the Catalogue tab. sde-vapps:

1. downloads the Debian 13 container image to the node (if it isn't there);
2. creates a container with its own SSH key, and installs xrdp (from backports), the vApp kit, and what the template holds: Chromium, Pale Moon and the Flash plugin's libraries for Web browsers, or the app for a catalogue template;
3. removes the container's identity (SSH host keys, machine id: every clone gets its own) and turns it into a template.

It takes 3–15 minutes. The Templates table shows each step and the build log, then, for each template: when it was built, by which sde-vapps and from which recipe version, and what it holds (xrdp, browser and app versions). Out of date means its recipe or sde-vapps has changed since: rebuild it. Each row has Rebuild and Remove; removing a template leaves the hosts already built from it running. With local storage, each node that should run a kind of vApp needs that template ("Best node" picks the one with the most free memory). Nodes whose pve-container is too old are listed with the reason.

6.1 File transfer (automatic)

A vApp's Drive passthrough (moving files between the user's PC and the app: downloads and uploads, section 7.2) needs FUSE in its host. Proxmox lets only root@pam turn that on, so no API token can do it. The bootstrap script (section 3) installs sde-vapps-fuse.timer on its node, which turns FUSE on for every container in the sde-vapps pool every 2 minutes: templates, web hosts and catalogue hosts. A running host only gets it after a restart, so sde-vapps restarts each Drive host once nobody is signed in to it (activity log: reason=fuse).

bash pve-bootstrap-sde-vapps.sh --enable-files           # do it now (and install the timer)
bash pve-bootstrap-sde-vapps.sh --enable-files --check   # just report
bash pve-bootstrap-sde-vapps.sh --remove-timer           # take the timer away
journalctl -u sde-vapps-fuse                             # what the timer changed

Readiness lists any template or host still without it ("File transfer (FUSE)"); on a site set up before the timer existed, run the script once more as root. Proxmox notes that FUSE in a container can stop snapshot-mode backups from freezing it: vApp hosts are rebuilt from templates rather than restored, so that's rarely a concern.

In a session, each mapped drive appears in ~/thinclient_drives/<display>/, a separate folder for each session, so two users of one kiosk account never see each other's PC.

7. Create a web vApp

vApps → New vApp → Modern web app (or Legacy web app). The fields:

Create, then watch the tile on the Overview: "cloning", "starting", "configuring", then Published, usually within a minute or two. Edits reach the host within seconds of saving.

Open sessions and edits. Clicking the tile again reconnects users to the session they left (it carries on where they were). A running browser can't pick up a new target, extra addresses, host names, lock-down or profile, so saving one of those closes that app's open sessions, and the next click opens the new settings. Other changes (who gets it, passthrough, size) leave open sessions alone. Rebuild host replaces the container (users on it are disconnected).

7.1 The browser users get

• Modern web apps open in a full Chromium window, maximised: address bar, tabs, back and forward, and the downloads button. Only the target, the "Also allow" addresses and the host names you listed load. Anything else typed in the address bar, or reached by a link, is refused by the browser's policy. There are no developer tools, extensions, guest profiles or browser sign-in.
• Legacy web apps open in Pale Moon with its full toolbar, downloads button included, and with Flash. The container's outbound firewall lets it reach only the target, and Flash runs only for the target's address.
• Closing the browser window ends the session. Dialogs (save, upload, print) always open in the middle of the screen.

7.2 Files and downloads

With the vApp's Drive passthrough on (and FUSE turned on, section 6.1), users can move files between the web app and their own PC:

• Downloads: both browsers ask where to save every download. The save dialog's sidebar has a Mapped folders entry, which holds the folders the user's PC shares into this session. In SDE Remote, that's the user's own Windows profile folder, shown as Home. Files Chromium flags as dangerous are blocked.
• Uploads: the site's upload button opens the same dialog; the user picks a file from Mapped folders.
• In a browser tab (Guacamole rather than SDE Remote), Mapped folders holds Guacamole's own file drive instead. Users move files between it and their PC from Guacamole's menu (Ctrl+Alt+Shift).
• Drive off (on the vApp, or site-wide on the gateway): there are no mapped folders. A file saved anywhere else stays on the web host, out of the user's reach, and is wiped at the end of the session when the profile is clean.

Each session has its own folder of mapped drives, so two people using one kiosk account never see each other's files.

8. Catalogue, hosted and RDS vApps

8.1 Apps from the catalogue

The Catalogue tab lists open-source apps sde-vapps can build and run for you, each from a recipe: what to install, and which app(s) it publishes. Built in, by category:

• Programming: Visual Studio Code, VSCodium (its open-source build), Kate, Notepadqq (like Notepad++), Geany, Code::Blocks, Spyder, Thonny.
• Electronics: Arduino IDE, KiCad, Fritzing.
• Office and publishing: LibreOffice (Writer, Calc, Impress), Scribus, Dia.
• Graphics: GIMP, Inkscape, Krita, darktable.
• 3D and CAD: Blender, FreeCAD, OpenSCAD, PrusaSlicer.
• Audio, music and video: Audacity, MuseScore 3, LMMS, Kdenlive, Shotcut.
• Maths, science and geography: GNU Octave, QGIS. Game development: Godot 3.
• Games: 0 A.D., OpenTTD, Battle for Wesnoth, Freeciv, Chess (Stockfish).
• Retro computing: Commodore 64 (VICE, with the 1541 drive) and ZX Spectrum (Fuse).

The app catalogue page lists every app with its licence, notes and suggested size.

All are open source except Visual Studio Code (Microsoft's licence, free to use). Downloads from outside Debian (Arduino IDE, VS Code, VSCodium, the C64 ROMs from VICE's release) are checked against the checksums their makers publish.

1. On the app's card, Build template (once per node that will run it).
2. New vApp on the card (or vApps → New vApp → App from the catalogue): choose the app (LibreOffice: which of Writer, Calc and Impress), who gets it, how users sign in, and whether it may reach the internet.
3. sde-vapps clones a host from the template, sets it up like a web host (sign-in, firewall, file transfer) and publishes the tile.

Recipes you add. Import recipe on the Catalogue tab takes a recipe file (JSON); Export on any card saves one, as a starting point or to move it to another site. A recipe has an id, a name, a version, Debian packages, optional shell steps, and its apps (id, name, command). A recipe runs as root, with internet access, while its template builds: import only recipes from people you trust, and read "What it installs" on the card first. Imported recipes are kept in data/recipes with the unit's state. Change a recipe by importing it again with a higher version: its templates then show Out of date.

8.2 Hosted and RDS vApps

• App on a host: build the host with the vApp host kit (hosted app KB), then New vApp → App on a host: the host's address, the app ID from its /etc/sde/apps.d, and the sign-in. sde-vapps only publishes it.
• RDS RemoteApp: your Windows admins publish the app in the RDS collection (RDS KB), then New vApp → RDS RemoteApp: the Connection Broker, the RemoteApp alias (||WINWORD) and the collection's load-balance info.

9. What users see

• Links and shortcuts: right-click any tile in SDE Remote → Create desktop shortcut / Copy link; web pages can link straight to a vApp page. See Links and shortcuts.
• In a browser: the vApp appears in the Guacamole home page under "Apps (open in SDE Remote)". Clicking it opens just the app in the tab.
• In SDE Remote: vApps have their own Apps section, above Desktop pools and Remote desktops (the headers show when a user has more than one kind of tile). Clicking a tile opens just the app in its own window through the gateway. RDS RemoteApps open as ordinary windows on the user's taskbar.
• Signing in: SDE Remote signs in the way the browser does. A vApp set to their own account opens signed in as the user, with no prompt. A kiosk vApp signs in with its kiosk account. An Ask vApp asks the user for an account when it opens.
• Closing the app ends the session. Reopening within the disconnect limit (2 h) returns to it.

10. Acceptance tests

• Readiness: no Fix lines.
• The web template is ready on the node(s) you'll use.
• A modern web vApp reaches Published, and a granted user gets just the app (browser and SDE Remote), signed in as themselves (AD) with no password prompt after the first time if "Remember sign-ins" is on.
• In SDE Remote, the tile is under Apps.
• In the app, typing another site in the address bar (or following a link elsewhere) is refused by the browser.
• With Drive on: a download asks where to save, Mapped folders → Home is in the dialog's sidebar, and the file arrives on the user's PC. An upload from the same folder works.
• From the web host, nothing but the target answers (sde-vapps' setup proves it: curl to another site fails).
• A legacy kiosk vApp opens in Pale Moon on the target, and a new session starts clean.
• Readiness → Flash: the plugin is listed with its version. In a legacy vApp, about:plugins lists Shockwave Flash, your Flash content plays, and Flash content from any other address doesn't.
• A user without the grant doesn't see the tile; with AD sign-in, the host refuses them too.
• deploy-sde-vapps.sh --check: /sde-vapps/v1/ and /sde-vapps/host/ are refused through the portal.

11. Day-to-day operations

12. Security model and hardening

• Everything goes through the gateway. The user's device only ever receives an RDP stream; the browser that talks to the internal app runs inside your network.
• Two locks on every web host: the browser's own policy (only the target and the listed addresses load, whatever is typed in the address bar; no developer tools, extensions or guest profiles), and an outbound firewall inside the container (only DNS, the target and the DCs). The firewall is enforced whatever Proxmox's firewall does.
• Files: files reach the user's PC only through the Drive passthrough, and only into the folders the user's PC shares. Turn Drive off on a vApp to stop file transfer for it, or across the site with the gateway's lock-down (SDE_DISABLE_DRIVE=true). The browser asks where to save every download and blocks files it flags as dangerous.
• Inbound: sde-vapps sets each host's Proxmox firewall to accept only RDP from the gateway and SSH from sde-vapps. Those rules apply only when Proxmox's datacenter firewall is on (Readiness warns when it's off). Check the node rules allow your management access before turning it on.
• Unprivileged containers, one per web vApp, so apps never share a host. Each clone gets fresh SSH host keys and machine id; sde-vapps pins each host's SSH key on first contact.
• Accounts: kiosk passwords are random and stored only in sde-vapps' state (mode 600) and the Guacamole connection. The AD join account is delegated to one OU, never a Domain Admin.
• SDE_VAPPS_V1_NETWORKS set; SDE_VAPPS_ALLOW_OPEN never set on production sites; the environment file chmod 600; Proxmox's certificate verified (SDE_VAPPS_PVE_CA_FILE).

13. Troubleshooting

The common problems are below. More (sound, AD join, template builds, SDE Networks, looking inside a host) are in Troubleshooting SDE vApps.

14. Removing SDE vApps

1. Delete each vApp in the admin page (web hosts are destroyed, Guacamole entries removed).
2. Hosts: the web templates can be deleted in Proxmox (pool sde-vapps).
3. gl -d sde-vapps, remove the nginx block, reload nginx.
4. Optionally remove the Proxmox pool, role, user and token, and the AD OU and join account.