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

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 get01
- 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_v2with 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 button02
- 01Open 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. - 02Choose a subscription, a new resource group and a region, and fill in the parameters below.
- 03Create the deployment, and wait until it is complete. It finishes once the installer has.
- 04Under the deployment's Outputs, copy
setupLinkand 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. - 05With a domain of your own, point its CNAME record at the
fqdnoutput, or an A record atpublicIp. Caddy keeps trying until the name resolves, then gets the certificate.
Deploy with the Azure CLI03
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/24The command prints the outputs once the deployment is complete. Run setupLink from them, as in step 4 above.
Parameters04
| Parameter | What it is |
|---|---|
domain | The domain Kaeso answers on; empty uses the address's DNS name |
dnsLabel | The address's DNS name under <region>.cloudapp.azure.com; empty makes one from the resource group |
kaesoVersion | A release to install; empty installs the newest stable release |
vmSize, diskSizeGb, diskType | Standard_B2als_v2, 40 GB and Standard SSD by default |
adminUsername, authenticationType, adminPasswordOrKey | The server's administrator, with an SSH public key or a password |
sshSourceAddress | An address range that may reach SSH; empty keeps port 22 closed |
location | The region; the resource group's by default |
Keep the master key05
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.
Update06
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 know07
- 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 tested08
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 steps09
- Azure in the docs (opens in a new tab), with every parameter.
- Upgrades (opens in a new tab): how the updater installs new releases.
- Where to run Kaeso: how Azure compares with the other platforms.
By Kaeso Team


