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:
- Create the DNS records, for instance
customers.velonde.<your domain>andpublic.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. - Copy
patches/shinyproxy-external.yamlandpatches/shinyproxy-public.yamlfrom the example overlay of the release you run, and setfqdn:in each. - In
kustomization.yaml, list the components undercomponents:after../../base/deployand before the Redis component:../../base/audiences/externaland../../base/audiences/public. Underpatches:, add the patch files from step 2, and change the targets of the workspace's authentication patch and ofpatches/mail.yamlto{ kind: ShinyProxy, name: "workspace|apps" }. Without that change, the new servers take the workspace's login and its mail settings. - For the external server, copy
patches/auth-external.yamlfrom the example overlay, fill in your customers' identity provider and list it underpatches:as well. Its client secret isexternal-oidc-client-secretinsecrets.env. Register the external host name at that provider as described in the next section. For tokens at external APIs, setexternal_token_issuerand the related keys invelonde.env. - 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
kubernetesIngressPatchesof its patch file, and setexternal_tls_secretandpublic_tls_secretinvelonde.envfor 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:
- Create the DNS record for the new name.
- 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 thelogout-urlofpatches/auth-oidc.yamlfor the workspace's host name, and ofpatches/shinyproxy-apps.yamlfor the apps host. - Change
fqdn:in the patch. On a cluster, make sure the ingress controller has a certificate for the new name. - 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.