The three host names

A hub 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 hub's host name from --domain and puts apps. and registry. in front of it for the other two. The overlay holds all three.

Name	Serves	Where it is set
The hub's host name, hub.<your domain>	The login page, the IDE tiles and sessions, the admin page, and Grafana under /grafana/ when the hub has monitoring	patches/shinyproxy.yaml, fqdn:
The apps host, apps.hub.<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.hub.<your domain>	The hub's own container registry, with the images that carry your layer and every built app	registry= in hub.env, and patches/registry.yaml for its Ingress

Sessions and apps run in two separate servers, the hub'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 hub.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 hub 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 hub.<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 hub'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 hub.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 hub'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 hub.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 hub'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.

Change a host name

A host name is set in the patches above and, for the registry, in hub.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 hub.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 hub'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 hub'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.