Installing an SDE site with sde-install

1. What gets installed

Every part of SDE runs as a GLServer unit (one Docker container each) under /var/glitch-units/. The units join one Docker network called sde and reach each other by name. From outside the host, only the portal's port 443 is reachable.

nginx routes by path, so one address and one certificate serve everything:

The add-ons (SDE VDI, SDE vApps, SDE Devices) are installed separately; see their own guides.

2. Before you start

3. The sde-install commands

sudo deploy/installer/sde-install            # the menu
sudo deploy/installer/sde-install install    # a fresh site: Guacamole, then the core, then Check
sudo deploy/installer/sde-install guacamole  # install or repair Guacamole only
sudo deploy/installer/sde-install core       # gateway, nginx and SDE Network; the shared layout
sudo deploy/installer/sde-install check      # every smoke test, read-only
sudo deploy/installer/sde-install status     # components and versions

In the menu, Install SDE, Check, Status and Add a component → Guacamole (install or repair) work today. Add a component for the add-ons, Upgrade, Settings and Backups aren't built yet: they show a message and change nothing.

Every change is shown before it's made, and every file the installer rewrites is first copied to <file>.bak-YYYYMMDD-HHMMSS. Secrets are never printed in full. Each run is logged to /var/log/sde-install/ (root-only). Running a step again repairs it: values that are already set are kept.

4. Run the install

1. Copy or clone the repository onto the host and change to its folder.
2. Preview the run: sudo deploy/installer/sde-install --dry-run install. Answer the questions; nothing is changed.
3. Run it for real: sudo deploy/installer/sde-install install. It runs the Guacamole step (section 5), then the core step (section 6), then Check.
4. Read the final Check. It ends with All OK or N to fix, with a FIX line for each problem.

If the Guacamole step fails, the install stops there. Fix what it reports and run install again.

5. The Guacamole step

Questions

What it does

1. Installs the guac-db, guacd and guacamole units from their templates, unless they're already there (then their settings are kept).
2. Sets random MySQL root and guacamole user passwords in guac-db's enviroment (mode 600), once.
3. Writes Guacamole's MySQL schema (from the Guacamole image's initdb.sh --mysql) to guac-db/data/initdb/initdb.sql. MySQL loads it on its first start only.
4. Sets Guacamole to match usernames whatever their case (CASE_SENSITIVITY=disabled) and to serve at / (WEBAPP_CONTEXT=ROOT).
5. With AD: writes the LDAP_* settings (LDAPS, sAMAccountName usernames, group names from cn), turns on MYSQL_AUTO_CREATE_ACCOUNTS so AD users get a database record on first sign-in, and builds a Java truststore with your AD CA in guacamole/data/trust.
6. Creates the sde Docker network if needed and starts the three units in order, waiting for MySQL and then Guacamole to answer.
7. Creates the accounts (below) and then deletes guacadmin. Guacamole 1.6's API can't disable an account, so it's removed.
8. With a copy source: copies the connections and grants (below).
9. With AD and an installed gateway: adds the Guacamole-only accounts to the gateway's SDE_LOCAL_ACCOUNTS and offers to restart the gateway.
10. Runs the Guacamole checks.

Accounts

Both admin and gua_srv get every Guacamole system permission (ADMINISTER, create users, groups, connections, connection groups and sharing profiles).

Copying from an existing Guacamole

Give the old Guacamole's URL and an administrator account on it. The step reads, then copies:

• the connections at the root of the old connection tree, with their parameters (a connection with the same name already in the new Guacamole is left as it is);
• every user, each with READ on the copied connections they could use before.

Copied users get a random password. AD users sign in through AD as before; a local Guacamole user needs a new password set by an administrator. Connections in groups aren't copied: SDE VDI and SDE vApps re-create their own entries when they next start.

If another container already holds the port you chose to publish Guacamole on, the step offers to stop it (gl -d, answers key STOP_OLD_GUACAMOLE). Its data stays: gl -d guacamole then gl -s <old unit> brings it back.

6. The core step

Questions

What it does

1. Installs the sde-gateway, sde-nginx and sde-network units from their templates where they're missing.
2. Fills in the gateway's settings that aren't set yet: the service account (SDE_GUAC_ADMIN_USER, SDE_GUAC_ADMIN_PASS), SDE_GATEWAY_HOST, SDE_GATEWAY_PORT=443, a 32-character SDE_TOKEN_SIGNING_KEY, and with AD the SDE_LDAP_* settings (the CA is fetched from AD automatically). It writes the lock-down choices as SDE_DISABLE_* and the app version notice (SDE_APP_VERSION, SDE_APP_DOWNLOAD_URL) from versions.conf. See Gateway settings.
3. Adds a volume for the usage report's history (data/report), so it survives a container being recreated.
4. Puts every SDE unit on the sde network and points them at each other by name (http://guacamole:8080 and so on).
5. If you answered Yes to 443 only: stops the other units publishing ports (their lines in each unit's ports file are commented out). sde-nginx publishes 443.
6. Sets up SDE Network: its settings, SDE_GUEST_NETWORKS in every unit, and a route on the host to the address block through the edge router (sde-network-route.service).
7. Writes the nginx configuration (sde-nginx/data/config/default) from deploy/installer/templates/nginx-default.conf, with blocks for the installed units, and tests it with nginx -t before it goes live. A configuration that fails the test isn't installed.
8. Restarts the units that changed, in order: guac-db, guacd, guacamole, sde-network, the add-ons, sde-gateway, sde-nginx. A unit whose settings still contain __SET_ON_HOST__ isn't started.
9. Records the site in /etc/sde/install.conf (no secrets), waits for the portal to answer and runs Check.

7. Certificates and TLS

On SDE sites a load balancer or reverse proxy in front of the host presents the public certificate. Choose A load balancer or reverse proxy in front for these. nginx's own certificate is then internal: the core step makes a self-signed one for the FQDN (valid 10 years) in sde-nginx/data/certificates/ (cert.crt, cert.key). Check only warns if it is near expiry.

Choose nginx itself only where nothing sits in front and users see nginx's certificate. Give the full-chain certificate and its key as PEM files. Check then reports an expired or soon-expiring certificate as a FIX. To replace the certificate later, run sudo deploy/installer/sde-install core again, choose nginx itself and give the new files.

rdpgw also makes its own self-signed certificate on each start. Clients never see it: nginx talks to rdpgw over the internal network and doesn't check it.

8. Check and Status

sudo deploy/installer/sde-install check is read-only and safe to run at any time. Each line is OK, FIX, WARN or NOTE; the command exits with 1 when anything needs fixing. A copy is saved in /var/log/sde-install/.

sudo deploy/installer/sde-install status shows the site, whether gl works, each component with its running version against versions.conf, the last backup in /var/backups/sde/, and where the logs are.

9. First sign-in

1. Get the admin password if the installer chose it: sudo cat /etc/sde/secrets/guacamole-admin. Keep the file: Check uses it to find the installer-made admins.
2. Browse to https://<FQDN>/ and sign in as admin. You'll see Guacamole's home page.
3. In Settings, create or check your connections and give users (or AD groups) access to them.
4. In the SDE Remote app, enter https://<FQDN>/ as the Guacamole URL and sign in with a user account. Leave Broker URL empty: the app uses /sde-broker on the same server.
5. Open a Windows connection with native RDP to test the gateway. Use an AD account for this, not admin.
6. From inside the network, open the usage report at https://<FQDN>/sde-broker/report/ and sign in as a Guacamole administrator. See Using the usage report.

10. Updating images

The SDE units' unit.conf files use the :latest image tag (sde-remote-gateway:latest and so on). To move a unit to the newest published image, pull it and recreate the container. The gateway is the example:

docker pull "$(sed -n 's/^container=//p' /var/glitch-units/sde-gateway/glitch/config/unit.conf)"
gl -d sde-gateway && docker rm -f sde-gateway && gl -s sde-gateway
docker logs --tail 15 sde-gateway      # the start-up line shows the version
sudo deploy/installer/sde-install status
sudo deploy/installer/sde-install check

The docker rm -f matters: stopping and starting the unit alone can reuse the old container, with its old image and old settings.

• Status compares what's running with deploy/installer/versions.conf, the list of versions for this release of SDE. A unit on a different version shows spec is x.y.z.
• Guacamole and MySQL are pinned to exact tags in their unit.conf files (guacamole/guacamole:1.6.0, guacamole/guacd:1.6.0, mysql:8.4.13). The installer doesn't change these yet.
• sde-nginx (glitch-rproxy:latest) isn't versioned yet.

11. What to back up

sde-install doesn't take backups yet: the daily backup timer and the Backups menu come with the upgrade work. Until then, back these up yourself, and always before updating a unit:

12. Troubleshooting

13. Related pages

• SDE gateway settings reference: every gateway setting
• Sign-in, passwords and SyOps: sign-in, passwords and SyOps
• Using the SDE Remote usage report: using the usage report
• SDE Network: setup guide: setting up SDE Network after the install
• Installing the SDE Remote app: installing the SDE Remote app
• Setting up SDE VDI desktop pools, Setting up SDE vApps (one-click apps), SDE Devices: setup guide: the add-ons