Skip to content

Installing on a single host

One command on a fresh Ubuntu 24.04 server installs a complete hub: docker, k3s and Caddy on the host, the platform in the cluster, your configuration, your images, and a smoke test at the end. This page describes release v0.5.0; the version menu at the top switches to another.

You need the account for our distribution registry that came with your subscription. It fetches releases and platform images, and every upgrade.

Before you start

  • A server with Ubuntu 24.04, root or a user with sudo, and ports 80 and 443 open. Size it for the sessions: each IDE session and each running app is a container with the memory its user picked at start.
  • Three DNS records pointing at the server: hub.<your domain>, apps.hub.<your domain> and registry.hub.<your domain>. Without DNS you can still try the hub, see --trial below.

Install

curl -fsSLo install.sh https://images.hub.linnerprogramming.com/install.sh
bash install.sh install --domain hub.acme.example --email ops@acme.example --account acme

It asks for the account's password, then:

  1. fetches the newest release (or the one named with --version),
  2. writes your configuration, the overlay, to /opt/hub/overlay/<name>, or fetches the one we maintain for you and asks for the secrets it needs,
  3. installs docker, k3s and Caddy, which gets the TLS certificates from Let's Encrypt,
  4. applies the hub to the cluster,
  5. builds the customer layer of the images (your packages, certificates and templates on top of the platform images) and pushes it to the hub's own registry,
  6. runs the smoke test: it deploys a sample app from inside the cluster and removes it again.

At the end it prints the hub's address and the admin login. Options worth knowing:

--trial
No domain and no DNS. The hub answers under an sslip.io name made from the server's address. Good for a look, not for a customer's data.
--features r,python,deploy and --ides vscode,jupyterlab,rstudio
What the hub consists of. Dropping a feature or an IDE leaves its images out of the build and its tile off the landing page.
--auth oidc --oidc-issuer https://idp/realms/acme --oidc-client-id hub --oidc-client-secret …
Log in with your identity provider (Keycloak, Entra ID, Okta, Cognito) instead of the built-in admin. Register https://<fqdn>/login/oauth2/code/shinyproxy as the redirect URI and https://<fqdn> as the sign-out URL, for the hub and for the apps host name. --oidc-username-claim, --oidc-groups-claim and --admin-group name the claims and the admin group; the defaults are email, groups and hub-admins. LDAP and SAML are set up in the overlay by hand, see The overlay.
--version vX.Y.Z
A release other than the newest.

If your network needs its own CA certificates (a TLS-intercepting proxy, an internal package mirror), put them into /opt/hub/overlay/<name>/certs/ as .crt files before the install, or afterwards and run an upgrade to the same version.

What is now yours

Everything the installer wrote is yours. /opt/hub/overlay/<name> is the hub's configuration; secrets.env in it holds the generated passwords, so keep a copy in your password manager. The installer never overwrites the overlay: edit it and apply the change with

bash install.sh upgrade <the version you run>

Every key and file of the overlay is described under Configuration.

Upgrading and rolling back

bash install.sh upgrade latest     # or a version
bash install.sh rollback
bash install.sh status
bash install.sh diagnose           # one archive for us when something is wrong

upgrade fetches the release, backs the hub's namespace up where backups are configured, builds the customer layer for the new version, applies it and runs the smoke test. Sessions and apps keep running; new sessions start on the new images, and apps are rebuilt on their next deploy. The previous release stays under /opt/hub/releases, and rollback applies it again.

A release whose release notes say No rollback cannot be rolled back to its predecessor; rollback refuses and you restore from the backup instead.

diagnose writes one archive with the state of the host, your configuration without its secrets and certificates, the cluster's objects, the platform's logs and the public checks. Send it to us with a description of what you saw.