# Install on Azure App Service

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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](/docs/sentinel/v2/install/).

<Callout type="note" title="ARM template">

The ALTCHA ARM template (`altcha-sentinel-deploy-azure`) deploys Sentinel v1 and doesn't work with v2 yet: v2 needs a configuration file and uses different ports and health checks. Follow the steps on this page until a v2 template is released.

<!-- VERIFY: the az commands and App Service behaviour on this page (startup command as container arguments, X-Client-IP, 169.254.0.0/16 peers) have not been run against a live App Service yet. -->

## 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](/docs/sentinel/v2/configure/databases/#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.

<Callout type="warning" title="The admin sign-in is public">

With a single port, the admin UI is reachable from the internet. `allowed_ips` on the admin UI listener and App Service access restrictions would also block widget traffic, so neither can restrict it alone. Enable TOTP or a passkey for every user, starting with root.

## Prerequisites

- An Azure subscription and the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli), signed in with `az login`.
- A Sentinel license key. To get a trial, register at [cloud.altcha.org](https://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](/docs/sentinel/v2/plans/).
- `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:

```bash
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:

```bash
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](/docs/sentinel/v2/configure/secrets/).

## Step 2 — Create the resource group and App Service plan

```bash
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](/docs/sentinel/v2/install/#sizing).

## Step 3 — Create the database

```bash
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`:

```bash
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:

```toml
[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](/docs/sentinel/v2/configure/listeners/#client-ip).
- **`base_url`** is the app's public URL. It's also the passkey and OAuth URL; see [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/).
- **`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](/docs/sentinel/v2/reference/configuration/#database-tls).

If Docker is available on your machine, validate the file before you upload it, as shown in [Install with Docker](/docs/sentinel/v2/install/docker/#step-2--write-sentineltoml); export the variables from Step 1 and pass them with `-e`. Then upload it:

```bash
az storage file upload --account-name $SA --account-key "$SA_KEY" \
--share-name sentinel --source sentinel.toml
```

## Step 5 — Create the web app

```bash
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:

```bash
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:

```bash
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](https://learn.microsoft.com/azure/app-service/app-service-key-vault-references), such as `@Microsoft.KeyVault(SecretUri=…)`.

## Step 8 — Check the startup log

```bash
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.

> **Warning:**
>
> `[bootstrap] root_password` is applied only when the root user is created on first boot. Changing it later has no effect; change the password in the admin UI instead.

## 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](/docs/sentinel/v2/operations/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](https://learn.microsoft.com/azure/app-service/app-service-web-tutorial-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](/docs/sentinel/v2/operations/clustering/#requirements). 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](/docs/sentinel/v2/install/#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:

```toml
[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](/docs/sentinel/v2/configure/databases/).

3. **Turn off session affinity** (Sentinel doesn't need it) and add instances:

```bash
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](/docs/sentinel/v2/operations/clustering/#instance-slots).

## Update Sentinel

Before an update, read the release notes and take a snapshot, as described in [Before you update](/docs/sentinel/v2/operations/updating/#before-you-update). Then point the app at the new tag:

```bash
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](/docs/sentinel/v2/operations/updating/).

## Next steps

- [Create a security group and an API key](/docs/sentinel/v2/get-started/), then embed the widget with `https://<app>.azurewebsites.net` as the challenge URL.
- [Admin sign-in & SSO](/docs/sentinel/v2/security/sign-in/): passkeys, TOTP, and Microsoft Entra ID sign-in.
- [Snapshots & backups](/docs/sentinel/v2/operations/snapshots/): stored snapshots can go to Azure Blob Storage.
- [Install Sentinel](/docs/sentinel/v2/install/): production requirements, and the [Production checklist](/docs/sentinel/v2/security/production-checklist/).
