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 installwrites it from the options you gave, or syncs it from us if we maintain your configuration. Apply changes withbash install.sh upgrade <the version you run>. - On the jump host of your own cluster, it is at the same path.
install.sh generate --clusterwrites 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, orCLAUDE.mdandplugins.txtunderclaude-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/, orrules/andskills/underclaude-code/needs an image build, which takes minutes. So do thevelonde.envkeysai,features,cran,r_snapshot,py_snapshotandpypi_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_certortls_keyalso 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.envneeds 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-passwordinsecrets.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/shinyproxyand the sign-out URLhttps://<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-attributeis the user id (emailfor Keycloak,preferred_usernameoroidfor Entra ID).roles-claimcarries the groups (groupswith a group mapper in Keycloak,cognito:groupsfor Cognito). The client secret isoidc-client-secretinsecrets.env. The login uses PKCE (S256), which all of these providers support. The installer's--auth oidcwrites this patch. auth-ldap.yaml- LDAP and Active Directory. The user id is the login name (
uidorsAMAccountName). The password of the bind account isldap-manager-passwordinsecrets.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-attributeis the user id, androles-attributecarries the groups.
Whatever the backend, three rules apply:
- 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.
- Groups must arrive as group names.
admin-groupsin the auth patch andaccess-groupsin an app'svelonde.yamlrefer to the names the provider sends. - Apps read the user from the request, through
velonde::user()andvelonde::groups(). Group names reach an app upper-cased, so check membership withvelonde::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/externalandaudiences/public, the servers for apps that people outside the company open (see Host names for external and public apps), - one Redis:
singlefor one pod,sentinelfor three pods that survive the loss of a node, orexternalfor one you run, - one registry:
internalfor the platform's own behind the Ingress,externalfor Harbor or any other v2 registry, orecr, backup-holder, which mounts idle homes during the nightly backup. It does nothing unlessbackups=trueis set invelonde.env,- optionally
packageswith one database,packages-db/singleorpackages-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:
- List
../../base/packagesand../../base/packages-db/singleundercomponents:inkustomization.yaml, after../../base/deploy. Withpackages-db/externalinstead, the repository uses a PostgreSQL database that you run: setpackages_db_urlandpackages_db_userinvelonde.env. That user must own the database. - Add
packages-db-passwordtosecrets.env. The installer generates it on a new workspace. - 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:
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:
- Put the variables that are not secret into
apps-env/envand the secret ones intoapps-env/secrets.env, oneKEY=valueper line. - In
kustomization.yaml, remove the comment signs from the twoapps-enventries, the one underconfigMapGeneratorand the one undersecretGenerator. Use only the entry of a file you created. - 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.
- Edit
secrets.envand apply it withbash install.sh upgrade <the version you run>. - Delete the ShinyProxy pods, which start again with the new values: Sessions and apps survive, because their state is in Redis.
- After a change of
registry-passwordorregistry-build-password, also restart the deploy service and, if the workspace uses the platform's own registry (registry/internal), the registry:
redis-password cannot be changed on a running workspace without downtime. Set it before the first
install, as the installer does.