Install on Azure App Service
Run Sentinel on Azure App Service as a managed Linux container. This page sets it up with the Azure CLI: the container runs from the public image, reads sentinel.toml from an Azure Files share, keeps its data in Azure Database for PostgreSQL, and takes its secrets from app settings.
For the license, secrets, database, and Redis requirements of a production install, see Install Sentinel.
How it fits together
- One public port. App Service forwards HTTPS traffic to a single container port, set by
WEBSITES_PORT. This setup points it at the admin UI listener (port3002), which serves the admin app and the whole/v2API. Widgets, backends, and admins all usehttps://<app>.azurewebsites.net, as with Sentinel v1. - Configuration file on Azure Files. App Service can't mount a single file, so
sentinel.tomllives on a file share mounted at/mnt/sentinel, and the container's startup command passes--config /mnt/sentinel/sentinel.toml. - Secrets in app settings. App settings reach the container as environment variables, and
sentinel.tomlreferences them with${VAR}. - External database. Sentinel's embedded SQLite defaults to write-ahead logging, which doesn't work on network file systems such as Azure Files.
[database] sqlite_journal_mode = "delete"avoids that for a single instance (see SQLite on network storage), but this page keeps the database in Azure Database for PostgreSQL.data_dirstays on the container's local disk, so Sentinel downloads its remote files (about 230 MB with the default sources) again after each restart.
Prerequisites
- An Azure subscription and the Azure CLI, signed in with
az login. - A Sentinel license key. To get a trial, register at cloud.altcha.org and create a Sentinel V2 trial license in the Licenses section. PostgreSQL needs the
exotdb.backend.postgreslicense feature, which the trial and every paid plan include; see Plans & Licensing. opensslto generate secrets.
Step 1 — Choose names and generate the secrets
Set shell variables for the resource names. The app, storage account, and database server names must be globally unique:
RG=sentinel
LOCATION=westeurope
PLAN=sentinel-plan
APP=sentinel-example # https://sentinel-example.azurewebsites.net
PG=sentinel-example-db # sentinel-example-db.postgres.database.azure.com
SA=sentinelexampleconfig # 3–24 lowercase letters and digitsGenerate the secrets in the same shell:
SENTINEL_LICENSE_KEY='SENT-…' # your license key
ROOT_PASSWORD=$(openssl rand -base64 24) # first root password
DB_PASSWORD=$(openssl rand -hex 24) # hex: no escaping in the database URL
JWT_SECRET=$(openssl rand -hex 32)
ALTCHA_HMAC_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)Store them in a password manager or Azure Key Vault. Back up ENCRYPTION_KEY with the database: a different key can't read the API key and TOTP secrets stored in it. See Server secrets.
Step 2 — Create the resource group and App Service plan
az group create --name $RG --location $LOCATION
az appservice plan create --resource-group $RG --name $PLAN --is-linux --sku B2B2 (2 vCPU, 3.5 GB) is enough for an evaluation. For production, use Premium v3 (P1v3, 2 vCPU) or higher; see Sizing.
Step 3 — Create the database
az postgres flexible-server create --resource-group $RG --name $PG --location $LOCATION \
--version 17 --tier Burstable --sku-name Standard_B1ms --storage-size 32 \
--admin-user sentinel --admin-password "$DB_PASSWORD" \
--database-name sentinel --public-access None--public-access None enables public access without any firewall rule; Step 6 allows only the app's outbound addresses. A Burstable server suits an evaluation; use General Purpose for production. Sentinel creates its tables on first start.
Step 4 — Upload the configuration file
Create a storage account and a file share for sentinel.toml:
az storage account create --resource-group $RG --name $SA --location $LOCATION \
--sku Standard_LRS --kind StorageV2 --min-tls-version TLS1_2
az storage share-rm create --resource-group $RG --storage-account $SA --name sentinel --quota 1
SA_KEY=$(az storage account keys list --resource-group $RG --account-name $SA --query '[0].value' --output tsv)Create sentinel.toml, replacing sentinel-example and sentinel-example-db with your app and database server names:
[server.admin_ui]
enabled = true
host = "0.0.0.0"
trusted_proxies = ["169.254.0.0/16"] # App Service front ends connect from link-local addresses
client_ip_header = "X-Client-IP" # set by App Service to the client's IP
base_url = "https://sentinel-example.azurewebsites.net"
[database]
url = "postgres://sentinel:${DB_PASSWORD}@sentinel-example-db.postgres.database.azure.com:5432/sentinel?sslmode=verify-full"
[secrets]
jwt_secret = "${JWT_SECRET}"
altcha_hmac_secret = "${ALTCHA_HMAC_SECRET}"
encryption_key = "${ENCRYPTION_KEY}"
[license]
key = "${SENTINEL_LICENSE_KEY}"
[bootstrap]
root_password = "${ROOT_PASSWORD}" # applied on first boot only- Client IP. App Service sends
X-Forwarded-Forasip:port, which Sentinel skips, so the client IP comes fromX-Client-IP. The front ends overwrite that header, so clients can't set it themselves, andtrusted_proxiesaccepts it only from the front ends' link-local addresses. If you put Azure Front Door or Application Gateway in front of the app,X-Client-IPholds the gateway's address instead; use the header your gateway sets for the client IP. See Client IP. base_urlis the app's public URL. It's also the passkey and OAuth URL; see Admin sign-in & SSO.sslmode=verify-full. Azure Database for PostgreSQL requires TLS, and its certificate chains to a public CA in the image's CA store. See Database TLS.
If Docker is available on your machine, validate the file before you upload it, as shown in Install with Docker; export the variables from Step 1 and pass them with -e. Then upload it:
az storage file upload --account-name $SA --account-key "$SA_KEY" \
--share-name sentinel --source sentinel.tomlStep 5 — Create the web app
az webapp create --resource-group $RG --plan $PLAN --name $APP \
--container-image-name ghcr.io/altcha-org/sentinel:2.0.0-beta.1 --https-only trueUse an exact 2.0.0-beta.x tag; during the beta, latest still points to Sentinel v1. App Service starts the container straight away, without a configuration file, and the start fails until Step 7. That's expected.
Step 6 — Let the app reach the database
Add a firewall rule for each address the app may connect from:
for ip in $(az webapp show --resource-group $RG --name $APP \
--query possibleOutboundIpAddresses --output tsv | tr ',' ' '); do
az postgres flexible-server firewall-rule create --resource-group $RG --server-name $PG \
--name "app-${ip//./-}" --start-ip-address $ip --end-ip-address $ip
doneThe outbound addresses can change when you move the plan to another pricing tier; run the loop again after a change. For production, consider VNet integration and private access to the database instead of public firewall rules.
Step 7 — Configure the app
Set the app settings, mount the file share, and set the startup command:
az webapp config appsettings set --resource-group $RG --name $APP --settings \
WEBSITES_PORT=3002 \
WEBSITES_ENABLE_APP_SERVICE_STORAGE=false \
SENTINEL_LICENSE_KEY="$SENTINEL_LICENSE_KEY" \
ROOT_PASSWORD="$ROOT_PASSWORD" \
DB_PASSWORD="$DB_PASSWORD" \
JWT_SECRET="$JWT_SECRET" \
ALTCHA_HMAC_SECRET="$ALTCHA_HMAC_SECRET" \
ENCRYPTION_KEY="$ENCRYPTION_KEY"
az webapp config storage-account add --resource-group $RG --name $APP \
--custom-id sentinel-config --storage-type AzureFiles \
--account-name $SA --share-name sentinel --access-key "$SA_KEY" \
--mount-path /mnt/sentinel
az webapp config set --resource-group $RG --name $APP \
--startup-file="--config /mnt/sentinel/sentinel.toml" \
--always-on true \
--generic-configurations '{"healthCheckPath": "/"}'
az webapp restart --resource-group $RG --name $APPWEBSITES_PORT=3002sends traffic to the admin UI listener.WEBSITES_ENABLE_APP_SERVICE_STORAGE=falsekeeps App Service from mounting its shared storage over/home, which would hide the image's working directory/home/nonroot.- Startup command. The image's entrypoint is the
altcha-sentinelbinary, so the startup command becomes its arguments. Write it with=, or the CLI reads--configas one of its own options. - Always On keeps the app loaded while it's idle, so Sentinel keeps refreshing its license and remote files.
- Health check.
GET /on the admin UI listener answers200with the app's page. With several instances, App Service replaces one that stops answering. - To keep the secrets out of the app settings, store them in Key Vault and set each value to a Key Vault reference, such as
@Microsoft.KeyVault(SecretUri=…).
Step 8 — Check the startup log
az webapp log config --resource-group $RG --name $APP --docker-container-logging filesystem
az webapp log tail --resource-group $RG --name $APPThe log shows database opened … backend=Postgres, the license status (for example licensed to "…"), created root user from bootstrap.root_password, web app listening addr=0.0.0.0:3002, and listening addr=0.0.0.0:3000. A configuration error stops the container, and the log names the key and the reason.
Step 9 — Sign in
Open https://<app>.azurewebsites.net and sign in with the username root and the password in $ROOT_PASSWORD. Enable TOTP or a passkey for root right away.
Verify it works
As root, open Doctor in the admin UI sidebar and switch Checks shown to All:
storage.dbreports the database connection.security.client_ipreportspeerTrusted: truewith a169.254.…peer. If it warns that the request came through an untrusted proxy, add the reported peer address totrusted_proxies.security.admin_uiwarns that the admin UI listens beyond loopback withoutallowed_ips. That's expected with this setup.
See Doctor & troubleshooting for the other checks.
Custom domain
Map a custom domain and add a managed certificate as described in Set up an existing custom domain. Then change base_url in sentinel.toml to the new URL, upload the file again, and restart the app. Passkeys are bound to the base_url host, so registered passkeys don't work on a new domain.
Scale out
Several instances keep Sentinel available while App Service restarts or replaces one. Every instance must share a Redis-compatible KV store in addition to the database and secrets; see Clustering & high availability. The instance count is capped by the license's instances limit.
Create a Redis. Use Azure Managed Redis with the Enterprise clustering policy, which serves the whole cache on one endpoint, or any Redis 7.0+ the app can reach. Size it with Redis or Valkey and set its eviction policy to
noeviction.Add it to
sentinel.toml, with the password in a new app settingREDIS_PASSWORD, then upload the file again:[redis] nodes = ["rediss://:${REDIS_PASSWORD}@sentinel-example.westeurope.redis.azure.net:10000"]Sentinel connects to a single node as a standalone server and treats several
nodesas Redis Cluster seed nodes, so the OSS clustering policy, which expects a cluster-aware client on its one endpoint, doesn't work with a single entry. See Databases & KV store.Turn off session affinity (Sentinel doesn't need it) and add instances:
az webapp update --resource-group $RG --name $APP --client-affinity-enabled false az appservice plan update --resource-group $RG --name $PLAN --number-of-workers 2Check the cluster. Open Cluster in the admin UI: it lists one replica per instance, each with its own host name. Sentinel uses the host name as the node ID of the license instance slot.
Update Sentinel
Before an update, read the release notes and take a snapshot, as described in Before you update. Then point the app at the new tag:
az webapp config container set --resource-group $RG --name $APP \
--container-image-name ghcr.io/altcha-org/sentinel:2.0.0-beta.2
az webapp restart --resource-group $RG --name $APPThe new container migrates the schema at startup. With a single instance, Sentinel is unavailable while the container restarts. See Updating Sentinel.
Next steps
- Create a security group and an API key, then embed the widget with
https://<app>.azurewebsites.netas the challenge URL. - Admin sign-in & SSO: passkeys, TOTP, and Microsoft Entra ID sign-in.
- Snapshots & backups: stored snapshots can go to Azure Blob Storage.
- Install Sentinel: production requirements, and the Production checklist.