Skip to content

The three host names

A workspace answers under three host names, and every install needs DNS and TLS for all three. This page explains what each name serves and how to set up DNS, TLS and the identity provider for them. The installer takes the workspace's host name from --domain and puts apps. and registry. in front of it for the other two. The overlay holds all three. Two more names are optional, for apps that people outside the company open. See Host names for external and public apps.

Name Serves Where it is set
The workspace's host name, velonde.<your domain> The login page, the IDE tiles and sessions, the admin page, and Grafana under /grafana/ when the workspace has monitoring patches/shinyproxy.yaml, fqdn:
The apps host, apps.velonde.<your domain> The apps page, every deployed app under /app/<name>, every API and MCP server under /api/<name>/ patches/shinyproxy-apps.yaml, fqdn:. Only with the deploy feature.
The registry, registry.velonde.<your domain> The workspace's own container registry, with the images that carry your layer and every built app registry= in velonde.env, and patches/registry.yaml for its Ingress

Sessions and apps run in two separate servers, the workspace's and the apps', so that registering an app never restarts anyone's IDE. Each server needs a host name of its own. The apps server is the one behind the apps host. Some changes to an app, such as new settings in its velonde.yaml, restart the apps server, which takes about a minute: apps that are open keep running, and during that minute the apps host may not open new ones.

The registry needs the third name, because the image build on the host or jump host pushes to it, and the cluster's nodes pull from it, by name over TLS. On a cluster with a registry of your own, registry= names that registry, and the workspace needs no registry name of its own.

DNS

On a single host, create three A records pointing at the server, or one A record for velonde.<your domain> and two CNAME records pointing at it. On a cluster, point the names at the ingress. The records must exist before the install, because the installer pushes the customer layer to the registry's name and the smoke test opens the workspace's.

With --trial you need no DNS records: the installer makes names under sslip.io from the server's address.

TLS

On a single host, the installer's Caddy obtains and renews Let's Encrypt certificates for all three names, with acme_email as the contact. For that, ports 80 and 443 must be reachable from the internet. To use your own certificate instead, set tls_cert and tls_key in velonde.env to two files on the host. acme_email can then stay empty. An upgrade to the version you run applies the change. To renew the certificate, replace the files and reload Caddy with sudo systemctl reload caddy.

On a cluster, the ingress controller terminates TLS, or a proxy in front of it does. The registry's Ingress carries the TLS setting the controller needs in patches/registry.yaml, for instance cert-manager's annotation. The Ingresses of the workspace's host name and of the apps host carry it in the kubernetesIngressPatches of patches/shinyproxy.yaml and patches/shinyproxy-apps.yaml. The Ingress of each deployed API names the TLS Secret that api_tls_secret in velonde.env gives for the apps host. Without that key, the controller's default certificate must cover the apps host.

Register the names at the identity provider

A user logs in at both the workspace's host name and the apps host, so register both as redirect targets. For OpenID Connect, register https://<host name>/login/oauth2/code/shinyproxy and the sign-out URL https://<host name>. For SAML, register https://<host name>/saml/SSO. Authentication has the details for each provider.

Host names for external and public apps

An app with audience: external or audience: public in its velonde.yaml runs on a server of its own, behind a host name of its own (see Publish outside the company). The external server has a login of its own, typically the identity provider your customers have accounts in. The public server has no login. A workspace has these servers only when its overlay lists them. Each costs one more ShinyProxy pod, which requests a quarter of a CPU and 768 MiB of memory.

To add one or both:

  1. Create the DNS records, for instance customers.velonde.<your domain> and public.velonde.<your domain>. On a cluster, route them through whatever your network exposes to the internet, which may be another ingress than the one of the workspace's other names.
  2. Copy patches/shinyproxy-external.yaml and patches/shinyproxy-public.yaml from the example overlay of the release you run, and set fqdn: in each.
  3. In kustomization.yaml, list the components under components: after ../../base/deploy and before the Redis component: ../../base/audiences/external and ../../base/audiences/public. Under patches:, add the patch files from step 2, and change the targets of the workspace's authentication patch and of patches/mail.yaml to { kind: ShinyProxy, name: "workspace|apps" }. Without that change, the new servers take the workspace's login and its mail settings.
  4. For the external server, copy patches/auth-external.yaml from the example overlay, fill in your customers' identity provider and list it under patches: as well. Its client secret is external-oidc-client-secret in secrets.env. Register the external host name at that provider as described in the next section. For tokens at external APIs, set external_token_issuer and the related keys in velonde.env.
  5. Run an upgrade to the version you run. On a single host, it adds the names to Caddy, which obtains their certificates. On a cluster, give each server's Ingress its TLS setting in the kubernetesIngressPatches of its patch file, and set external_tls_secret and public_tls_secret in velonde.env for the Ingresses of external and public APIs.

To remove a server, delete or move its apps first: an app whose audience has no server stays out of every apps page until it moves.

Change a host name

A host name is set in the patches above and, for the registry, in velonde.env. The registration at the identity provider refers to it, and so does every link people have saved.

To change the registry's name, create the DNS record for the new name, set registry= in velonde.env and run an upgrade to the version you run. The upgrade applies the new name first, builds the images into it, and restarts the pods that read the name. The deploy service then rewrites the image names of every app, so apps keep working without a redeploy.

To change the workspace's host name or the apps host:

  1. Create the DNS record for the new name.
  2. Register the new name at the identity provider. With OpenID Connect, the overlay also names it in the sign-out URL: change post_logout_redirect_uri (with Cognito, logout_uri) in the logout-url of patches/auth-oidc.yaml for the workspace's host name, and of patches/shinyproxy-apps.yaml for the apps host.
  3. Change fqdn: in the patch. On a cluster, make sure the ingress controller has a certificate for the new name.
  4. Run an upgrade to the version you run. On a single host, that upgrade renders Caddy's configuration again, so the new name gets its certificate.