Instance settings for self-hosted owners

The settings in this page live under Settings, in the Platform group (Traefik, Instance, Maintenance) and the Enterprise group (License, Branding). The Platform group is hidden on the Hosted instance. For installing the instance in the first place, see Install Cloudgate.

What you can do

• Activate or release an Enterprise license for an Organization.
• Rename and recolour the console with your own branding.
• Serve the console on a domain, and see the instance’s version and health.
• Set how many builds and Cloud runs the server runs at once, and how long a Requested preview may live.
• Edit Traefik’s files, restart it, and turn on request metrics.
• Reclaim disk and schedule nightly clean-ups.
• Connect container registries, and manage the SSH keys Cloudgate signs in to Servers with.

Activate an Enterprise license

1. Turn on enterprise features

   Open Settings > License and switch on Use enterprise features in this Organization. Activation is refused while that switch is off.

2. Paste the key and activate

   Paste the key you were sent (it looks like CG-XXXX-XXXX-XXXX) and press Activate. Cloudgate checks it with the license server before storing it. The status reads Licensed, with the date the license runs until.

A license unlocks custom roles, single sign-on, SCIM, forward auth, more than one Organization, branding, and parallel builds and Cloud runs. Release the key frees it, also on the license server, so you can activate it on another instance. Owners and admins see a bar across the console from 14 days before the license ends.

Brand the console

Settings > Branding replaces Cloudgate’s look across the instance. It needs an active Enterprise license.

• Name and marks: Name (replaces Cloudgate in the tab title, beside the mark and on the sign-in screen), Logo URL and Favicon URL.
• Colors: Primary (buttons, the focus ring, the first chart series; their label is white, so choose a dark enough colour) and Accent (links and highlights). One colour serves both themes, so check it in light and dark.
• Error pages: your own text for Page not found and Page failed, and a Support URL.
• Custom CSS: a stylesheet loaded on every signed-in page, up to 50,000 characters.

Empty a field and save to put Cloudgate’s own back.

Check the instance and its health

Settings > Instance shows:

• This instance: the version, mode and image tag running, and the newest published version.
• Public address: the address people reach this instance on. Cloudgate does not detect it.
• Health: whether PostgreSQL and Traefik answer.

Serve the console on a domain

Settings > Instance > Console domain routes a hostname to the console through Traefik, over HTTPS with a Let’s Encrypt certificate (give an email) or One of your own certificates. The Console routing card under it says whether that hostname’s origin is trusted yet.

Sign-in on the new hostname is refused until its origin is trusted. Add it in Settings > Single sign-on > Trusted origins (licensed), or in TRUSTED_ORIGINS in /etc/default/cloudgate-backend followed by systemctl restart cloudgate-backend. Live screens (logs, shells, setup output) also need the API on the same hostname, and the address the console calls is built in, so that part is a rebuild of the console, not a setting.

Set build and Cloud run limits

Card	What it sets
Concurrent builds	How many Deployments this server builds at once, 1 to 100. Each is a full image build using CPU, memory and disk.
Cloud runs	How many Cloud runs this server runs at once (each is an OpenTofu process of about 0.8 GB), and a Time limit, in minutes after which a run is stopped and ends as an error.
Requested preview lifetime	The longest a Requested preview may be asked to live, in minutes. 1,440 (24 hours) by default. Lowering it does not shorten previews already running.

Work with Traefik

Settings > Traefik is the Traefik container that serves every app on the Cloudgate server.

• Files: Main configuration (traefik.yml), Shared middlewares (including the redirect to HTTPS every HTTPS domain uses) and This console’s router.
• Its environment variables and published ports.
• Publish the dashboard on 8080: opens Traefik’s dashboard with no password. Leave it off on a public server.
• Restart Traefik: needed after editing traefik.yml, which is read once at start. It interrupts live traffic.
• Request metrics: lets Traefik count requests, which is what each Service’s Error rate is read from. Turning it on restarts Traefik.

Remote Servers have the same switches for their own Traefik on their Settings tab. See Monitoring for what request metrics feed.

Keep the disk clean

Settings > Maintenance shows Docker’s Disk usage and two ways to reclaim it.

• Reclaim disk: Remove stopped containers, Remove unused images, Remove unused volumes, Empty the build cache and Delete metrics, each on its own. Each Docker command first waits up to 10 minutes for any build or pull to finish.
• On a schedule: Prune Docker every night at 23:50 (on by default; never touches volumes) and Rotate Traefik’s access log.

Settings to leave alone

Connect a registry

Settings > Registries > Connect a registry stores a login for pulling and pushing images: a name, whether it is Hosted by someone else (such as Docker Hub) or One you run, the hostname, an image prefix, a username and a password or access token. Press Test connection before you save. An Application’s build can then push its image there instead of keeping it on the build Server. Cloud Services never use a registry.

Manage SSH keys

SSH keys belong to the Organization and are managed from Servers > Manage SSH keys: press Generate one or Paste one I have. Each key shows the line that goes in a machine’s ~/.ssh/authorized_keys. A Server’s Access tab changes which key it uses, and shows its host key fingerprint. See Servers.

The machine Cloudgate runs on

The platform host is the machine Cloudgate itself runs on. It has no Server row of its own, so an Environment can choose This Cloudgate host as its Deploy target. On Servers, the This host card opens a shell on it; only owners and admins of the Instance organization see it. Its GPU setup, metrics and Traefik are the Instance organization’s too.

Mirror or turn off the Template catalogue

The Templates screen reads the official Template catalogue, one catalogue.zip from the newest release of octabyte-io/cg-templates, with nothing to set. Only the backend fetches it, from github.com and release-assets.githubusercontent.com. It checks for a newer release at most once an hour, only when someone opens the Templates screen, and keeps the last good copy to show, with its age, while GitHub cannot be reached.

CLOUDGATE_TEMPLATES_URL in /etc/default/cloudgate-backend changes where it comes from. Restart cloudgate-backend after changing it.

Value	What happens
Not set	The official catalogue, https://github.com/octabyte-io/cg-templates/releases/latest/download/catalogue.zip.
The http or https address of your own copy of a release’s catalogue.zip	A mirror, for a network that blocks GitHub. Copy the release’s zip as it is published.
off	Templates are off, and the Templates screen says so.

The zip is checked whole before anything in it is read. One holding anything a template does not (a website’s index.md or screenshots/, a stray file) is refused, and so is a mirror that still serves a release’s older catalogue.json; the last good copy is kept until it serves the zip.

What you cannot do here

Related pages

• Install Cloudgate and Self-hosting Cloudgate.
• Single sign-on and SCIM, Members and roles and the Audit log.
• Deployments for the build queue, and Previews.
• Templates for what the catalogue offers once it is read.
• Self-host Cloudgate for the overview.

Questions

Who can change the instance settings?

The owners and admins of the Instance organization, the first Organization on the instance. People only: an Agent never can, even one in that Organization.

Why does the console still build one Deployment at a time after I raised Concurrent builds?

The setting is saved, but it takes effect only while an Enterprise license is active. Without one, each Server builds one Deployment at a time.

Can I update Cloudgate from the console?

Not on a native install. Update and restart is turned off there. Pull the new version and run the install script again.