Skip to content

Deploy Kaeso on Azure

Run Kaeso on one Azure virtual machine from the Deploy to Azure button or the Azure CLI. The installer runs at first boot, and the setup link comes through Cloud Shell without SSH.

Published
Reading time
3 min
Author
Kaeso Team
A bright gradient of coral and pink, in upright folds like a curtain, with a warm light in one corner

Kaeso's Azure template is a quick server: the Compose package on one virtual machine, as on your own server, with Caddy for TLS, a bundled ClickHouse for request logs and the updater. It needs no domain of its own to start, since Azure gives the machine a DNS name and Caddy gets a certificate for it. The whole deployment takes about five minutes.

deploy/azure/ in the repository holds the Azure Resource Manager template, and createUiDefinition.json beside it shapes the portal's form.

What you get

  • A virtual network with one subnet, and a network security group that lets in HTTP, HTTPS and HTTP/3 only, and SSH only from an address range you give.
  • A static public address with a DNS name under <region>.cloudapp.azure.com.
  • An Ubuntu 24.04 virtual machine with Trusted Launch, boot diagnostics and a 40 GB disk, Standard_B2als_v2 with 2 vCPUs and 4 GB by default.
  • A Custom Script extension that runs Kaeso's installer at the first boot: it installs Docker, writes the settings and starts the Compose package.

The template holds none of Kaeso's secrets. The installer generates the master key and the passwords on the server itself.

Deploy with the button

  1. Open Deploy to Azure (opens in a new tab) and sign in. The portal reads the template from the branch prod, which holds the latest release.
  2. Choose a subscription, a new resource group and a region, and fill in the parameters below.
  3. Create the deployment, and wait until it is complete. It finishes once the installer has.
  4. Under the deployment's Outputs, copy setupLink and run it in Azure Cloud Shell (opens in a new tab) or with the Azure CLI. It prints the one-time setup link without SSH. Open it to create the first user.
  5. With a domain of your own, point its CNAME record at the fqdn output, or an A record at publicIp. Caddy keeps trying until the name resolves, then gets the certificate.

Deploy with the Azure CLI

From a clone of the repository, create a resource group and deploy the template into it:

az group create --name kaeso --location westeuropeaz deployment group create --resource-group kaeso \  --template-file deploy/azure/quick-server.json \  --parameters domain=kaeso.example.com \  adminPasswordOrKey="$(cat ~/.ssh/id_ed25519.pub)" sshSourceAddress=203.0.113.0/24

The command prints the outputs once the deployment is complete. Run setupLink from them, as in step 4 above.

Parameters

ParameterWhat it is
domainThe domain Kaeso answers on; empty uses the address's DNS name
dnsLabelThe address's DNS name under <region>.cloudapp.azure.com; empty makes one from the resource group
kaesoVersionA release to install; empty installs the newest stable release
vmSize, diskSizeGb, diskTypeStandard_B2als_v2, 40 GB and Standard SSD by default
adminUsername, authenticationType, adminPasswordOrKeyThe server's administrator, with an SSH public key or a password
sshSourceAddressAn address range that may reach SSH; empty keeps port 22 closed
locationThe region; the resource group's by default

Keep the master key

Kaeso encrypts provider keys with the master key in /opt/kaeso/master-keys, so a backup of the database can't be read without it. Keep a copy apart from your backups: run the setupLink output's command with cat /opt/kaeso/master-keys as its script to print it, and put it in a password manager.

Update

Updates work as on any Compose install: from the console, automatically in a window you choose, or by hand. The template only creates the server; deploying it again doesn't update Kaeso.

Good to know

  • This is a quick server only. The repository has no template for Azure Container Apps with Azure Database for PostgreSQL and a managed cache yet.
  • The sizes are x64. For an Arm64 size, deploy Ubuntu 24.04 for Arm64 and run the installer by hand.

What was tested

The template passes Microsoft's ARM template test toolkit. It hasn't been deployed from an empty Azure account yet; the same installer has, on AWS and Google Cloud. If you deploy it, tell us how it went.

Next steps

By Kaeso Team

On this page

Own the gateway.Own the record.

curl -fsSLhttps://kaeso.app/install.sh | sh