Skip to content

Installing on a single host

This page shows how to install Velonde on a fresh Ubuntu 24.04 server with one command. The installer sets up docker, k3s and Caddy on the host, the platform in the cluster, your configuration and your images, and runs a smoke test at the end.

You need the account for our distribution registry that came with your subscription. The installer uses it to fetch releases, platform images and your license, at the install and at 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 what runs at the same time. Each IDE session is a container with the memory its user picked at start. Each running app gets the memory its velonde.yaml sets, 2 GB by default, and each build of an app takes up to 6 GB while it runs.
  • Enough cores for the apps you expect to run at once. The workspace's quota counts what containers reserve, and the installer sets it to the server's cores minus two and three quarters of its memory (patches/quota.yaml in the overlay). An IDE session reserves a quarter of its CPUs and half of its memory. An app container or an API reserves an eighth of the CPUs and a quarter of the memory its velonde.yaml gives it, 0.25 CPUs and 512 MB with the default 2 CPUs and 2 GB, and may use up to those limits. A Shiny app starts one container per viewer unless seats-per-container lets viewers share one. On a server with 16 cores and 64 GB, ten small IDE sessions and thirty-five viewers of apps with the default settings fit in the quota. A pipeline run reserves all its limits while it runs. Set ide_idle_timeout in velonde.env, because by default an idle IDE session is never stopped. The alert VelondeQuotaAlmostFull tells you when to raise the quota.
  • Three DNS records pointing at the server: velonde.<your domain>, apps.velonde.<your domain> and registry.velonde.<your domain>. The three host names explains what each one serves. Without DNS you can still try the workspace, see --trial below.

Install

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

--domain is the workspace's full host name. The installer puts apps. and registry. in front of it for the other two names, and takes the workspace's name (acme) from it unless you give --name. --email is the address Let's Encrypt sends notices about the certificates to.

Check the installer before you run it

We sign every release, and the installer in it, with our release key. Before the first run, check that the install.sh you downloaded is the one we signed:

curl -fsSLo install.sh.sig https://images.hub.linnerprogramming.com/install.sh.sig
echo 'velonde-release namespaces="velonde-release" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGh2xKaKVNsFnlYNpH7UIUCRYewkQCdyPQVefp/AqPtq velonde-release' > velonde-allowed-signers
ssh-keygen -Y verify -f velonde-allowed-signers -I velonde-release -n velonde-release -s install.sh.sig < install.sh

The last command prints Good "velonde-release" signature. The key's fingerprint is SHA256:+24ZNycmHDQdXdOLbCCMpjPpdtE58mjTxZcMG2ftRIM. The mail with your account names it as well, so compare the two. From then on, the installer checks every release and every overlay it fetches against the same key and refuses one that we did not sign.

The installer asks for your account's password and then works through these steps:

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

At the end it prints the workspace's address.

The server's firewall

The installer does not set up a firewall, and it does not change one that the server has. The workspace needs ports 80 and 443 open to its users, and port 22 or whatever you use to administer the server. Nothing else has to be reachable from outside: the Kubernetes API listens on an address inside the server only, and the registry, the apps and Grafana are served through Caddy on port 443. Close every other port, with your provider's firewall or with ufw on the server. We run the workspace with ufw active and only these three ports allowed.

The installer adds one rule of its own, in a table named velonde_pod_guard that leaves your firewall's rules as they are. It keeps every container from the link-local addresses (169.254.0.0/16), where cloud providers serve the metadata of a virtual machine, which can include its credentials. sudo nft list table inet velonde_pod_guard shows the rule.

These options of the installer are worth knowing:

--trial
Installs without a domain or DNS records. The workspace answers under an sslip.io name made from the server's address. Use it to try the workspace. It is not meant for real data.
--features r,python,deploy and --ides vscode,jupyterlab,rstudio
Select what the workspace consists of. packages added to the features (r,python,deploy,packages) gives the workspace its package repository. If you drop an IDE, its image is left out of the build and its tile does not appear on the landing page. Without deploy the workspace has no apps server, no deploy service and none of their images. The features r and python only select what the coding agents are told. They remove no image and no tile.
--user-networks "10.20.0.0/16 10.0.5.10/32:5432"
The private networks that sessions, apps and builds may reach, such as your databases, package mirrors and identity provider, each as a network or a network with ports. Without it, user code reaches the internet and no private address. You can change the list later as user_networks in velonde.env.
--auth oidc --oidc-issuer https://idp/realms/acme --oidc-client-id velonde --oidc-client-secret …
Users log in with your identity provider over OpenID Connect (Keycloak, Microsoft Entra ID, Okta, Auth0 and Cognito, for example) instead of as the built-in admin. Register https://<host name>/login/oauth2/code/shinyproxy as the redirect URI and https://<host name> as the sign-out URL, for the workspace's host name and for the apps host. --oidc-username-claim, --oidc-groups-claim and --admin-group name the claims and the admin group. The defaults are email, groups and velonde-admins. You set up LDAP and SAML by hand in the overlay, see The overlay.
--monitoring --alerts-to ops@acme.example --smtp-host smtp.acme.example --smtp-from velonde@acme.example --secret smtp-password=…
Adds the dashboards and the alert mail described in Operating a workspace, and the "Report issue" button in the workspace's menu, which mails the same address. --smtp-port (default 587) and --smtp-user (default: the sender) complete the mail account. The monitoring stack needs about 2 GB of memory.
--bucket velonde-acme --object-store-endpoint https://s3.acme.example --secret object-store-access-key=… --secret object-store-secret-key=…
Turns the daily backups on, into that S3-compatible bucket. Leave the endpoint out for AWS S3 itself, and give --object-store-region when the region is not us-east-1. Operating a workspace describes the backups and the restore.
--version vX.Y.Z
Installs a release other than the newest. We keep the six newest releases available.
--license <file>
Installs the license from a file we sent you, instead of fetching it with your account.

Every account on the server can read the installer's command line while it runs, and with it a value given as --secret smtp-password=…. On a server that others log in to as well, put such values into a file that only you can read and pass the file instead: --secret-file <file> takes one key=value per line, --password-file <file> holds your account's password and --oidc-client-secret-file <file> the client secret. The environment variables VELONDE_SECRETS, VELONDE_DISTRIBUTION_PASSWORD and VELONDE_OIDC_CLIENT_SECRET work the same way.

If your network needs its own CA certificates (for a TLS-intercepting proxy or an internal package mirror), the images must carry them from the first build:

  1. Write the overlay first, with the same options you would give install: bash install.sh generate --domain velonde.acme.example --email ops@acme.example --account acme.
  2. Put the certificates into /opt/velonde/overlay/acme/certs/ as .crt files.
  3. List each file in the ca-certificates ConfigMap in the overlay's kustomization.yaml. The entry is there as a comment. The images trust every file in certs/, and ShinyProxy, which handles the login, trusts the files that ConfigMap lists.
  4. Install with that overlay: bash install.sh install --overlay /opt/velonde/overlay/acme --account acme.

If you add certificates to a workspace that runs, run an upgrade to the version you already run, which rebuilds the images that carry them.

If an install stops before the end, for example because DNS is not in place yet, fix the cause and run the same install command again. It continues with the overlay the first run wrote, and with its passwords.

Your configuration

Everything the installer wrote belongs to you. /opt/velonde/overlay/<name> is the workspace's configuration. The secrets.env file in it holds the generated passwords, so keep a copy in your password manager. The installer never overwrites an overlay it generated. Edit it, then apply the change with:

bash install.sh upgrade <the version you run>

On a single host, this upgrade also renders Caddy's configuration again, so a new host name or your own certificate takes effect.

If we maintain the overlay for you, every upgrade replaces it with the version we publish. Any edit you made on the host is kept as a copy under /opt/velonde/state/<name>/, and the upgrade says so. Send us such a change instead of editing the overlay.

Configuration describes every key and file of the overlay.

Upgrade and roll 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

Sessions and apps keep running during an upgrade. On a host that runs several workspaces, name the workspace with --name <name> in upgrade, rollback and diagnose. Routine tasks describes what each command does, when a release cannot be rolled back, and what to send us with a diagnose archive.