The SDE vApps app catalogue

1. How the catalogue works

Each app in the catalogue comes from a recipe: the Debian packages and setup steps that install it, and the app(s) it publishes. sde-vapps builds a template from the recipe once per node, then clones a host from that template for each vApp. You don't build or patch the hosts by hand.

Open the admin page → Catalogue. Each card shows the app's category, licence, whether it's built in or imported, its recipe version, its notes, its templates per node, and What it installs (the packages, steps and app commands). Cards marked Uses the internet have Internet access on by default.

2. The built-in apps

37 apps, all on Debian 13. Memory and CPU are the recipe's suggestion for one user, preselected in the editor; add about 1 GiB per extra active user. Internet is the default for the vApp's Internet access: with it off, the host reaches only DNS and the domain controllers.

The Web browsers template (Chromium and Pale Moon, for modern and legacy web vApps) is also a built-in recipe. It's built from the Hosts tab and isn't listed on the Catalogue tab.

3. Limits that apply to every app

• No GPU. Hosts are containers, so 3D, video and games render on the CPU. Heavy GPU work belongs on a GPU desktop pool.
• No USB. A container can't take a USB device: the Arduino IDE compiles sketches but can't upload them, and Thonny can't reach MicroPython boards. For boards connected with SDE Devices, use a Linux desktop pool (a VM) with the app installed.
• Keyboard and mouse only. RDP carries no gamepads. The emulators can map a joystick to keys.
• One window. The app runs maximised, with no desktop, panel or menu. Closing it ends the session.
• Files move between the app and the user's PC through the vApp's Drive (file transfer) passthrough, on by default for catalogue apps. It needs FUSE on the host (see troubleshooting).

4. Downloads from outside Debian

Most apps come straight from Debian's packages. These recipes also download something, and the build checks it against the checksum its maker publishes, failing if it doesn't match:

5. Publish an app

1. On the app's card, click Build template. sde-vapps picks the node with the most free memory; to choose a node, use Hosts → Templates, pick the app and a node, and click Build. Build it once on each node that will run the app if your nodes use local storage.
2. When the card shows <node>: ready, click New vApp on the card.
3. Check the name, choose Which app if the recipe publishes more than one (LibreOffice: Writer, Calc or Impress), set Who gets it, Users sign in with and Internet access, and click Create.
4. sde-vapps clones a host (sde-app-<id>), sets up sign-in, the firewall and file transfer, then publishes the tile. Each vApp has a host of its own.

The fields are described in the settings reference.

6. Import and export a recipe

6.1 Export

Click Export on any card, built in or imported. Your browser saves <id>.recipe.json. Use it as a starting point for a recipe of your own, or to move an imported recipe to another site.

6.2 Write or change a recipe

A recipe is a JSON file. A small one:

{
  "id": "gnumeric",
  "name": "Gnumeric",
  "category": "Office",
  "icon": "sheet",
  "licence": "GPL",
  "homepage": "http://www.gnumeric.org/",
  "version": 1,
  "description": "A light spreadsheet.",
  "notes": "Turn Drive on so users can open and save files on their PC.",
  "packages": ["gnumeric"],
  "script": [],
  "apps": [
    { "id": "gnumeric", "name": "Gnumeric", "exec": "gnumeric" }
  ],
  "memory": 1024,
  "cores": 1,
  "disk": 8,
  "internet": false
}

• id: 1–31 lower-case letters, digits or dashes. It can't be web or the id of a built-in recipe.
• packages: Debian 13 package names from main or contrib. A package from anywhere else needs steps in script that add its source (see the ZX Spectrum recipe), or the build stops with apt's exit 100.
• script: shell lines, one per entry, run as root with sh -eu after the packages: any failing line stops the build. 64 KB at most. Lines that print VERSION <name> <version> are shown in the template's contents.
• apps: 1–10 apps, each an id, a name and a command. The build fails with "app <id>: <program> isn't installed" if the command's program isn't there. Games in /usr/games are found.
• memory (MiB), cores, disk (GiB): defaults 2048, 2 and 8.
• version: raise it every time you change the recipe (section 8).

Every field is listed in the settings reference.

6.3 Import

1. On the Catalogue tab, click Import recipe and choose the JSON file.
2. sde-vapps checks it and says what's wrong if it can't be used ("Not imported: …"). Importing a file with the same id as an imported recipe replaces it; built-in recipes can't be replaced.
3. Build its template and create a vApp, as in section 5.

Imported recipes are kept in the unit's data folder (recipes/, alongside the state) and the activity log records each import with its packages and script length. Delete on an imported card removes it from the catalogue; it's refused while a vApp uses it. Its templates stay until you remove them on the Hosts tab.

7. How a template is built

A build takes 5–15 minutes (the Web browsers template about 10). Its progress shows on the Hosts tab, step by step:

1. downloading Debian 13: the Debian 13 container image, if the node doesn't have it.
2. creating the container: an unprivileged container in the 7000–7099 range, 2 GiB and 2 cores, with the recipe's disk size, on vmbr0 (or the node's first bridge), named sde-tpl-<recipe>.
3. starting.
4. installing xrdp and <app>: the host kit (xrdp from Debian backports, the app-only session, PipeWire for sound, FUSE tools for mapped drives), the common base (locale, firewall, AD tools), then the recipe's packages and steps.
5. sealing: SSH host keys and the machine id are removed, so every host cloned from it gets its own.
6. converting to a template.

The building container needs the internet (or a Debian mirror) throughout. If a step fails, the row shows the error (and a Build log when there's no working template on that node), and the half-built container is removed. If a template already existed on that node, it stays in use until a new build succeeds, then the old one is removed. Hosts already cloned from it keep running.

8. Out of date templates and rebuilds

Each template records the recipe version it was built from, the host kit version, the sde-vapps version that built it, and what the build reported (xrdp, browser and package versions). The Hosts tab's Templates table shows these.

Rebuilding a template doesn't touch hosts already running: Rebuild host on a vApp replaces its container with a fresh clone of the current template (users on it are disconnected). Settings changes and new sde-vapps versions reach existing hosts without a rebuild, because sde-vapps sets each host up again whenever its settings or setup script change. Only what's installed in the template needs a rebuild.

A template can't be removed while a vApp is waiting for a host from it.

9. Related pages

• Setting up SDE vApps (one-click apps): setting up SDE vApps
• SDE vApps settings reference: every setting and Readiness check
• Troubleshooting SDE vApps: symptoms, causes and fixes
• Building a host for an "App on a host" vApp: apps the catalogue doesn't have, on a host you build