Skip to content

The overlay

Everything specific to your workspace lives in one directory, the overlay: host names, identity provider, secrets, package stack, limits and the content your coding agents get. This page describes its files and what a change to each of them costs.

The platform contains none of this, so an upgrade replaces the platform and does not change an overlay that you wrote or that the installer generated. An overlay we maintain for you is replaced on every upgrade with the version we publish, except secrets.env and certs/. Send us changes to such an overlay instead of editing it on the host. The same overlay can be applied to a single host or to a cluster.

Where the overlay lives:

  • On a single host, it is in /opt/velonde/overlay/<name>. install.sh install writes it from the options you gave, or syncs it from us if we maintain your configuration. Apply changes with bash install.sh upgrade <the version you run>.
  • On the jump host of your own cluster, it is at the same path. install.sh generate --cluster writes it, or it is synced from us. Apply changes the same way, from the jump host.

Two files hold most of the configuration. velonde.env contains the typed settings, with a comment at every key (the reference lists them all). secrets.env exists only on your host, and nothing we exchange with you contains it.

Files

File What it holds
velonde.env Every typed setting: features, registry, package snapshots, sizes, limits. Reference.
secrets.env Passwords and keys, one per line (see Secrets). Ignored by git and kept out of every artifact.
velonde.license The workspace's license, which the installer fetches or takes from a file. It exists on your host only, and bash install.sh license replaces it.
kustomization.yaml What the workspace consists of: the IDE tiles in landing-page order, the deploy component, the package repository and the Grafana tile, which Redis and which registry, which auth patch, and the CA certificates that ShinyProxy and the app builds trust.
namespace.yaml The Kubernetes namespace of this workspace. Each workspace has its own namespace, and several workspaces can share a cluster. Keep its label hub.linnerprogramming.com/velonde: "true": the dashboards accept the workspace only from a namespace that carries it.
patches/shinyproxy.yaml, patches/shinyproxy-apps.yaml The workspace's host name and the apps host, and the ingress class of their Ingresses.
patches/auth-*.yaml The identity provider (see Authentication). kustomization.yaml names the one in use.
patches/quota.yaml What the workspace may use of the cluster: CPU, memory, number of pods.
patches/registry.yaml The registry's Ingress: class and TLS.
patches/deploy-egress.yaml The address and port of the Kubernetes API, which the deploy service may reach although the workspace keeps user code and the deploy service from every private address. What else they may reach there is user_networks in velonde.env.
patches/monitoring.yaml, patches/mail.yaml Grafana behind the workspace's host name, and the "Report issue" mail. Listed in kustomization.yaml with the monitoring stack and with a mail account.
r-packages.txt, python-packages.txt The package stack, one package per line. It is installed into the IDE images and into the base images that apps are built on.
apt-packages.txt, setup.sh System packages (Ubuntu 24.04 names), and any other setup that the IDE images and the base images of deployed apps need. Both are applied when the images are built. The deploy service does not get them.
egress-allow.txt Hosts that user code may reach through the proxy when egress=proxy in velonde.env, in addition to the platform's list. One per line, # starts a comment. A host such as data.example.org admits that name, and a domain with a leading dot such as .example.org admits the domain and every name below it. A change takes effect at the next apply, without a restart.
certs/*.crt CA certificates your network needs. Every image trusts them. ShinyProxy and the app builds trust only the files listed in the ca-certificates entry of kustomization.yaml, so list each file there. They exist on your host only.
branding/ Your logo and favicon, and pages of your own for each server of the workspace (see Branding).
templates/<name>/ Project templates for velonde::new_app() and RStudio's New Project dialog, and, when the directory has a pyproject.toml, Python templates for velonde new. They replace or add to the platform's templates of the same name. {{APP_NAME}} in any file or path becomes the project's name, {{MODULE_NAME}} its Python import name.
claude-code/ Your additions for the coding agents: CLAUDE.md, rules/, skills/, plugins.txt.
volumes.yaml Network shares that sessions and apps mount, with the users and groups who get each (see Shared volumes).
mcp-servers.yaml Hosted MCP servers that every user's coding agent gets, such as a wiki or a ticket system (see MCP servers for everyone).
monitoring/ The dashboards and the alert mail. Optional, and applied when the directory exists. The installer's --monitoring option writes it. The mail account and the recipients are keys of velonde.env.
apps-env/env, apps-env/secrets.env Optional variables for every deployed app (see Variables for every app). The second file exists on your host only.
generated/ Written by the scripts at every apply. Do not edit it.

You apply every change with bash install.sh upgrade <the version you run>. What a change costs:

  • A change to velonde.env, kustomization.yaml, the patches, or CLAUDE.md and plugins.txt under claude-code/ needs only an apply. Sessions and apps keep running. If the change restarts the platform's pods, it takes effect for new sessions. After every apply the apps server restarts, which takes about a minute: apps that are open keep running, and during that minute the apps host may not open new ones.
  • A change to the package stack, apt-packages.txt, setup.sh, certs/, templates/, or rules/ and skills/ under claude-code/ needs an image build, which takes minutes. So do the velonde.env keys ai, features, cran, r_snapshot, py_snapshot and pypi_index. New sessions start on the new images. The upgrade builds only when the files the images are built from changed, and then restarts the deploy service.
  • On a single host, a change to the host names, acme_email, tls_cert or tls_key also changes the host's Caddy configuration, which the upgrade renders again. A new host name for the workspace or the apps host also needs a new registration at the identity provider, as The three host names describes.
  • A change to secrets.env needs a restart after the apply, as described under Secrets.

Authentication

The workspace authenticates users through ShinyProxy, so any backend ShinyProxy supports works. The overlay ships one patch per kind of backend, and kustomization.yaml lists the one in use. Each patch says what to register at the provider.

auth-simple.yaml
Built-in users. Use them to bring a workspace up and for the smoke test. The admin's password is simple-admin-password in secrets.env.
auth-oidc.yaml
OpenID Connect, for Keycloak, Microsoft Entra ID, Okta, Auth0 or Cognito. Register a client with the redirect URI https://<fqdn>/login/oauth2/code/shinyproxy and the sign-out URL https://<fqdn> (exactly, without a trailing slash) for both host names: velonde.<your domain> and the apps host, apps.velonde.<your domain>. The patch names the claims. username-attribute is the user id (email for Keycloak, preferred_username or oid for Entra ID). roles-claim carries the groups (groups with a group mapper in Keycloak, cognito:groups for Cognito). The client secret is oidc-client-secret in secrets.env. The login uses PKCE (S256), which all of these providers support. The installer's --auth oidc writes this patch.
auth-ldap.yaml
LDAP and Active Directory. The user id is the login name (uid or sAMAccountName). The password of the bind account is ldap-manager-password in secrets.env. Groups come from the group search and are matched by name.
auth-saml.yaml
SAML 2.0, for ADFS, Entra ID, Okta or Shibboleth. Register the service provider for both host names with the ACS URL https://<fqdn>/saml/SSO. name-attribute is the user id, and roles-attribute carries the groups.

Whatever the backend, three rules apply:

  1. The user id must be permanent. It names the user's home volume, owns their apps and identifies them to the deploy service. If you later change the backend or the id attribute, every existing home directory is orphaned.
  2. Groups must arrive as group names. admin-groups in the auth patch and access-groups in an app's velonde.yaml refer to the names the provider sends.
  3. Apps read the user from the request, through velonde::user() and velonde::groups(). Group names reach an app upper-cased, so check membership with velonde::in_group("finance", …), which ignores case. Do not read the user from environment variables: they belong to the container, not to the person using it.

Choose the components

components: in kustomization.yaml lists what the workspace consists of:

  • the IDE tiles, in the order of the landing page (vscode, jupyterlab, rstudio),
  • the deploy component, deploy: the apps server behind the apps host, and the deploy service,
  • optionally audiences/external and audiences/public, the servers for apps that people outside the company open (see Host names for external and public apps),
  • one Redis: single for one pod, sentinel for three pods that survive the loss of a node, or external for one you run,
  • one registry: internal for the platform's own behind the Ingress, external for Harbor or any other v2 registry, or ecr,
  • backup-holder, which mounts idle homes during the nightly backup. It does nothing unless backups=true is set in velonde.env,
  • optionally packages with one database, packages-db/single or packages-db/external: the workspace's package repository (see The package repository).

Remove the IDE tiles and the deploy component if you do not use them. The image build builds only what the components need.

features= in velonde.env says what the workspace is for (r, python, deploy and packages) and selects the rules, skills, plugins and instructions the coding agents get. Keep it in step with the components. With ai=false the workspace has no AI at all: the IDE images come without Claude Code and Posit Assistant, and none of the agent content is installed.

The package repository

The package repository holds R and Python packages that your users publish with velonde deploy, and every session and app build of the workspace installs from it (R and Python packages describes it for users). It runs RDepot, an open-source repository manager, in the workspace's namespace, and only the deploy service can publish to it. To add it:

  1. List ../../base/packages and ../../base/packages-db/single under components: in kustomization.yaml, after ../../base/deploy. With packages-db/external instead, the repository uses a PostgreSQL database that you run: set packages_db_url and packages_db_user in velonde.env. That user must own the database.
  2. Add packages-db-password to secrets.env. The installer generates it on a new workspace.
  3. Apply the overlay with bash install.sh upgrade <the version you run>.

The repository adds three pods that request about 1.3 GiB of memory together: the repository manager, the server that serves the packages, and PostgreSQL. The workspace's quota counts them. The installer's generate adds the components when --features includes packages.

Packages and images

r-packages.txt lists the R stack, pinned to the snapshot date in r_snapshot. python-packages.txt lists the Python stack, pinned by py_snapshot. Both are installed into the IDE images and into the base images that apps are built on, so an app that uses only the stack builds in seconds. deploy_mode decides whether an app may bring its own lock file on top of that.

To use a private mirror, set cran= (a Posit Package Manager URL keeps binaries), pypi_index= and sysreqs_api=. Put the CA certificates your network needs into certs/. The image build trusts them everywhere, including in Node, which Claude Code runs on. List each file in the ca-certificates entry of kustomization.yaml as well, so that ShinyProxy and the app builds trust it too. Put the system packages that the IDE images and the base images of deployed apps need into apt-packages.txt, and any other setup into setup.sh, which runs as root. These five images are Ubuntu 24.04. The deploy service is Debian and gets neither file.

All of this forms the customer layer. The platform images are the same for every customer and come from our registry. A generic build adds your files on top of them, and that build can run inside your network if it has to. Adding a certificate rebuilds only the customer layer, which takes minutes.

Branding

Each of the workspace's servers shows its own pages: the IDE server (workspace), the apps server (apps), and, if you added them, the server for external users (external) and the public one (public). Every page has a navigation bar with a name and an optional logo, which you set in velonde.env for all servers at once:

brand_name=Acme Analytics
brand_logo=branding/logo.svg
brand_favicon=branding/favicon.ico

Put the two files in the overlay directory under the names you give, and apply.

To change more than the name and the logo, give a server pages of its own. The workspace's servers run ShinyProxy, whose pages are templates: index.html (the landing page with the tiles), app.html (the page around a running app or IDE), admin.html, the fragments navbar.html and modal.html, and files under assets/ such as style sheets and images, which the server serves at /assets/. Place the files you change in the directory of the server:

branding/
  common/              files for every server
  velonde/                 the IDE server
    index.html
    assets/velonde.css
  apps/
  external/
  public/

A server uses its own directory over common/, and for every template it does not find there it uses its default. So a public server can look like your company's website while the IDE server keeps the default pages. Start each template from the one of the ShinyProxy version your workspace runs (v1.0.0 runs ShinyProxy 3.2.4), which you find in its repository, and link assets as th:href="@{/assets/velonde.css}".

What a change costs:

  • An apply restarts the servers whose pages changed, without interrupting open sessions. The apps server needs about a minute before it opens apps for new visitors.
  • Your templates use ShinyProxy's variables and scripts, which a new ShinyProxy version may change. Check your pages after every upgrade that the release notes say updates ShinyProxy, and adapt the templates to the new version's.
  • All pages of a workspace together may take 900 KiB, compressed. Link larger pictures or videos from a web server instead.

MCP servers for everyone

MCP servers that run outside the workspace, such as a company wiki, a ticket system or a database gateway, can reach every user's coding agent without each user adding them. List them in mcp-servers.yaml:

- name: wiki
  url: https://mcp.wiki.acme.example/mcp
  title: Company wiki
- name: tickets
  url: https://tickets.acme.example/mcp
  groups: [ support ]
  token: tickets-mcp-token

At every session start, the workspace registers each server in the user's Claude Code and, in RStudio, Posit Assistant, next to the MCP servers deployed on the workspace. groups limits a server to users in one of those groups. token names a key in secrets.env, whose value the agent sends as Authorization: Bearer <value>. Every user who gets the server can read that token in their agent's settings, so give it no more rights than the least privileged of them needs. A server in this file takes the place of a deployed MCP server with the same name. Run an upgrade to the version you run to apply a change. Users get it at their next session start.

Shared volumes

A team share, such as an NFS export, a Windows (SMB) share, CephFS, EFS or Azure Files, can appear in the sessions and apps of the users you choose. The workspace does not connect to the file server itself. The share is made available as a PersistentVolumeClaim in the workspace's namespace (see Make a file server available), and you name the claim in volumes.yaml:

- name: projects
  claim: projects-share
  description: Team project share
  access-groups: [ analysts ]
  write-groups: [ data-owners ]
  apps: read
- name: personal
  claim: home-drives
  sub-path: "home/{user-name}"
Key Default Meaning
name The folder name: the share appears at /srv/volumes/<name>. Lowercase letters, digits and dashes, at most 40 characters.
claim The PersistentVolumeClaim in the workspace's namespace.
description "" A note for the admins who read the file.
access-groups [] Groups whose members get the share.
access-users [] User ids that get the share, besides the members of access-groups. Without either list, every user of the workspace gets it.
write-groups [] Groups whose members may write to the share. With this key or write-users, everyone else who gets the share reads it only. Without either, everyone who gets the share may write.
write-users [] User ids that may write, besides the members of write-groups. A user who may write gets the share even when the access lists do not name them.
read-only false With true, nobody can write to the share, in sessions or in apps.
sub-path "" A folder of the share to mount instead of all of it, such as departments/finance. {user} stands for the user's id and {user-name} for its part before an @, so home/{user-name} gives every user their own folder.
apps read What deployed apps, APIs and pipelines may do with the share: none, read or write. A share with {user} or {user-name} in its sub-path is for sessions only.

Group names and user ids are compared without regard to case, as everywhere on the workspace.

In RStudio, VS Code and JupyterLab, the share appears at /srv/volumes/<name> and as a folder volumes in the file browser (see Shared volumes). An app, API or pipeline gets it when its velonde.yaml names it under volumes and the share admits the app's owner. The workspace checks that at every deploy and whenever the app starts. An app writes to the share only with apps: write, and where the share names writers, only when its owner is one of them. Only apps of the audience internal can mount a share, because a viewer reads the share through the app.

Every session and every app the workspace builds runs as the same Linux user, uid 1000. The file server therefore sees one user for everyone, and its own permissions cannot tell people apart. Who may read and write is decided by this file. A share whose permissions depend on each user's own account, such as NFSv4 with Kerberos or SMB with Active Directory accounts, does not work this way.

The folders of a sub-path should exist on the share. If one is missing, Kubernetes creates it on the file server as the root user. That works on most servers, but a server that maps root to an anonymous user may refuse it, and the session then does not start.

Make a file server available

A share reaches the workspace as a PersistentVolume, which says where the share is, and a PersistentVolumeClaim in the workspace's namespace that binds to it. On a single host installed with install.sh, the host can mount NFS version 4 and SMB shares. On your own cluster, the cluster needs a driver for your storage, which its administrator installs.

An NFS export, for a single host or a cluster whose nodes have the NFS client:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: projects-share
spec:
  capacity: { storage: 1Ti }
  accessModes: [ ReadWriteMany ]
  persistentVolumeReclaimPolicy: Retain
  storageClassName: ""
  mountOptions: [ nfsvers=4.1 ]
  nfs: { server: nfs.example.internal, path: /exports/projects }
  claimRef: { namespace: <the workspace's namespace>, name: projects-share }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: projects-share
  namespace: <the workspace's namespace>
spec:
  accessModes: [ ReadWriteMany ]
  storageClassName: ""
  volumeName: projects-share
  resources: { requests: { storage: 1Ti } }

A single host mounts NFS version 4 only. Version 3 needs the rpcbind service, which the installer keeps switched off because it would listen on a public port of the host.

A Windows or Samba share. The account's password goes into a Secret in the workspace's namespace, and the mount options make the files belong to the workspace's user:

apiVersion: v1
kind: Secret
metadata:
  name: projects-share-credentials
  namespace: <the workspace's namespace>
stringData: { username: svc-velonde, password: <the password>, domain: EXAMPLE }
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: projects-share
spec:
  capacity: { storage: 1Ti }
  accessModes: [ ReadWriteMany ]
  persistentVolumeReclaimPolicy: Retain
  storageClassName: ""
  mountOptions: [ dir_mode=0770, file_mode=0660, uid=1000, gid=1000, noperm, vers=3.0 ]
  csi:
    driver: smb.csi.k8s.io
    volumeHandle: projects-share
    volumeAttributes: { source: //fileserver.example.internal/projects }
    nodeStageSecretRef: { name: projects-share-credentials, namespace: <the workspace's namespace> }
  claimRef: { namespace: <the workspace's namespace>, name: projects-share }

The claim is the same as for NFS. Apply both with kubectl apply -f, then name the claim in volumes.yaml. The host or the nodes connect to the file server, not the sessions, so the workspace's network rules for user code do not need to open it.

On a cluster with more than one node, the claim must allow ReadWriteMany, or ReadOnlyMany for a read-only share, because sessions and apps on several nodes mount it at the same time. On a single host, any claim works. bash install.sh check reports a claim that is missing or that cannot be shared between nodes.

When a share cannot be mounted

A session or app that gets a share starts only when the share can be mounted. If the file server cannot be reached, the claim is missing or its password is wrong, the session of every user who gets that share fails to start after two minutes, with a message that the container did not start. On a workspace with the monitoring stack, the alert VelondeVolumeMountFailing names its PersistentVolume. kubectl describe pod on the waiting pod shows the reason. To let people work while the file server is down, take the share out of volumes.yaml and apply.

Apply a change

The workspace's backup leaves shared volumes out. Back up the share where it lives.

To apply a change, run bash install.sh upgrade <the version you run>. The IDE server and the apps server restart (about a minute, open sessions keep running). Users get the change at their next session start, and apps within a minute.

Variables for every app

An app gets its own variables from its .Renviron and from velonde env set. Variables that every app of the workspace needs, such as the address of a shared database, can come from the overlay instead:

  1. Put the variables that are not secret into apps-env/env and the secret ones into apps-env/secrets.env, one KEY=value per line.
  2. In kustomization.yaml, remove the comment signs from the two apps-env entries, the one under configMapGenerator and the one under secretGenerator. Use only the entry of a file you created.
  3. Apply with bash install.sh upgrade <the version you run>.

These variables reach internal apps only. An app with audience: external or public gets its own variables and nothing else, because the shared ones often include credentials for internal systems.

An app's own variables override these. Apps read them when their container starts, so an app that is open keeps the old values until it is started again. Like secrets.env, apps-env/secrets.env stays on your host: it is never part of a release, a synced overlay or a diagnose archive.

Secrets

secrets.env has one key per line. Do not put a comment after a value.

Key Used for
redis-password The workspace's Redis, where sessions live. Generated by the installer.
simple-admin-password The built-in admin with auth-simple.yaml.
oidc-client-secret The OpenID Connect client.
ldap-manager-password The bind account with auth-ldap.yaml.
registry-password The workspace's registry, with the user velonde or the one registry_user in velonde.env names: every pull of an image and every push of the platform.
registry-build-password With the workspace's own registry, the user build, which app builds push with. It may write only to the apps' images. Generated by the installer.
smtp-password The mail account that sends alerts and the "Report issue" mail.
heartbeat-url The ping URL of a heartbeat service, which alerts you when the monitoring stops. Optional, see Operating a workspace.
object-store-access-key, object-store-secret-key The S3 bucket for backups, the stateless registry and logs on the object store.
packages-db-password The database of the package repository. Generated by the installer.

The installer generates what it can and asks for the rest. Keep a copy of the file in your password manager: it exists nowhere else, and a diagnose archive never contains it.

Change a secret

A change to secrets.env alone does not restart anything, because the pods read their secrets when they start.

  1. Edit secrets.env and apply it with bash install.sh upgrade <the version you run>.
  2. Delete the ShinyProxy pods, which start again with the new values:
    kubectl delete pod -n <namespace> -l app=shinyproxy
    
    Sessions and apps survive, because their state is in Redis.
  3. After a change of registry-password or registry-build-password, also restart the deploy service and, if the workspace uses the platform's own registry (registry/internal), the registry:
    kubectl rollout restart deployment/velonde-deploy -n <namespace>
    kubectl rollout restart deployment/registry -n <namespace>
    

redis-password cannot be changed on a running workspace without downtime. Set it before the first install, as the installer does.