Skip to main content
ALTCHA®

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 (port 3002), which serves the admin app and the whole /v2 API. Widgets, backends, and admins all use https://<app>.azurewebsites.net, as with Sentinel v1.
  • Configuration file on Azure Files. App Service can't mount a single file, so sentinel.toml lives 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.toml references 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_dir stays 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.postgres license feature, which the trial and every paid plan include; see Plans & Licensing.
  • openssl to 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 digits

Generate 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 B2

B2 (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-For as ip:port, which Sentinel skips, so the client IP comes from X-Client-IP. The front ends overwrite that header, so clients can't set it themselves, and trusted_proxies accepts 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-IP holds the gateway's address instead; use the header your gateway sets for the client IP. See Client IP.
  • base_url is 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.toml

Step 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 true

Use 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
done

The 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 $APP
  • WEBSITES_PORT=3002 sends traffic to the admin UI listener.
  • WEBSITES_ENABLE_APP_SERVICE_STORAGE=false keeps 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-sentinel binary, so the startup command becomes its arguments. Write it with =, or the CLI reads --config as 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 answers 200 with 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 $APP

The 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.db reports the database connection.
  • security.client_ip reports peerTrusted: true with a 169.254.… peer. If it warns that the request came through an untrusted proxy, add the reported peer address to trusted_proxies.
  • security.admin_ui warns that the admin UI listens beyond loopback without allowed_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.

  1. 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.

  2. Add it to sentinel.toml, with the password in a new app setting REDIS_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 nodes as 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.

  3. 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 2
  4. Check 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 $APP

The new container migrates the schema at startup. With a single instance, Sentinel is unavailable while the container restarts. See Updating Sentinel.

Next steps

Start typing to search...

↑ ↓ Navigate ↵ Select