### Faster build workflow with just setup, cargo check --lib, and just check

Source: https://uptimepage.dev/docs/development

Faster build workflow: run just setup once, then use cargo check --lib for quick iteration and just check as the pre-commit gate. Requires mold on Linux (installed by just setup); macOS is opt-in.

```bash
just setup        # once: cargo-nextest and the linker
                  # (mold on Linux; macOS prints an lld opt-in snippet)
cargo check --lib # the iteration gate (~8.5s after a one-file edit)
just check        # builds every test binary — pre-commit gate (~4min)
```

--------------------------------

### Production deployment setup commands

Source: https://uptimepage.dev/docs/deployment

Commands to set up the production stack: change to the deployment directory, copy the environment template, edit the .env file with domain, ACME email, OAuth app, DB passwords, and KEK, then start the stack with docker compose.

```bash
cd deployment
cp .env.example .env
$EDITOR .env            # set domain, ACME email, OAuth app, DB passwords, KEK
docker compose up -d
copy
```

--------------------------------

### Host workflow: start dev stack, run binary, tear down

Source: https://uptimepage.dev/docs/development

Host workflow: start Postgres and ClickHouse, run the binary natively with the required opt-in env var, then tear down (optionally wiping data volumes).

```bash
docker compose -f compose.dev.yml up -d
```

```bash
UPTIMEPAGE_STORAGE__ALLOW_DEFAULT_CREDENTIALS=true cargo run --bin uptimepage
```

```bash
docker compose -f compose.dev.yml down
```

```bash
docker compose -f compose.dev.yml down -v
```

--------------------------------

### Docker prod-shape: build and start uptimepage

Source: https://uptimepage.dev/docs/development

Docker prod-shape workflow: build and start the uptimepage service using the build overlay to match the production build.

```bash
docker compose -f docker-compose.yml -f compose.build.yml up -d --build uptimepage
```

--------------------------------

### Install uptimepage Helm chart with secrets

Source: https://uptimepage.dev/docs/kubernetes

Install the uptimepage Helm chart on Kubernetes 1.29 or newer. Create the required secrets first, then run helm install with the domain and database URLs. The fingerprint salt is required and boot fails without it; the KEK must decode to exactly 32 bytes or stored credentials are left in plaintext.

```bash
kubectl create namespace uptimepage

kubectl -n uptimepage create secret generic uptimepage-core \
  --from-literal=fingerprint-salt="$(openssl rand -base64 32)" \
  --from-literal=credentials-kek-base64="$(openssl rand -base64 32)"

kubectl -n uptimepage create secret generic uptimepage-db \
  --from-literal=postgres-url='postgres://uptimepage:pw@pg.internal:5432/uptimepage?sslmode=require' \
  --from-literal=clickhouse-password='pw'

helm install uptimepage oci://ghcr.io/uptimepage/charts/uptimepage \
  --namespace uptimepage \
  --set domain=status.example.com \
  --set clickhouse.url=https://ch.internal:8443 \
  --set secrets.existingSecret=uptimepage-core \
  --set postgresql.existingSecret=uptimepage-db \
  --set clickhouse.existingSecret=uptimepage-db
copy
```

--------------------------------

### Docker dev workflow: start, logs, stop app

Source: https://uptimepage.dev/docs/development

Docker dev workflow: build and start the dev-app profile, follow logs, and stop only the app while keeping Postgres and ClickHouse running.

```bash
docker compose -f compose.dev.yml --profile dev-app up -d --build
```

```bash
docker compose -f compose.dev.yml logs -f uptimepage
```

```bash
docker compose -f compose.dev.yml stop uptimepage
```

--------------------------------

### POST /auth/passkey/register/start

Source: https://uptimepage.dev/docs/authentication

Begins adding a passkey. This endpoint is gated.

```APIDOC
## POST /auth/passkey/register/start

### Description
Begins adding a passkey. This endpoint is gated.

### Method
POST

### Endpoint
/auth/passkey/register/start

### Auth
- session

### Response
#### Success Response (200)
- Passkey registration initiation data

```

--------------------------------

### Terraform quick start: configure provider and create uptimepage_target

Source: https://uptimepage.dev/docs/terraform

Quick start configuration for the uptimepage/uptimepage Terraform provider. It declares the provider, sets credentials via variables or environment variables, and creates an HTTP monitor target. The endpoint defaults to https://app.uptimepage.dev; set it for a self-hosted instance.

```hcl
terraform {
  required_providers {
    uptimepage = {
      source = "uptimepage/uptimepage"
    }
  }
}

provider "uptimepage" {
  token = var.uptimepage_token # or set UPTIMEPAGE_TOKEN
  org   = "your-org-slug"      # or set UPTIMEPAGE_ORG
  # endpoint defaults to https://app.uptimepage.dev; set it for a self-hosted instance
}

resource "uptimepage_target" "api" {
  name     = "api prod"
  interval = 60
  check = {
    type = "http"
    http = {
      url             = "https://example.com/healthz"
      expected_status = { kind = "exact", exact = 200 }
    }
  }
}
```

--------------------------------

### POST /auth/passkey/login/start

Source: https://uptimepage.dev/docs/authentication

Begins a passkey sign-in, carrying any `invitation` / `redirect_after`. This endpoint is gated.

```APIDOC
## POST /auth/passkey/login/start

### Description
Begins a passkey sign-in, carrying any `invitation` / `redirect_after`. This endpoint is gated.

### Method
POST

### Endpoint
/auth/passkey/login/start

### Auth
- none

### Response
#### Success Response (200)
- Passkey login initiation data

```

--------------------------------

### GET /api/v1/me/api-tokens

Source: https://uptimepage.dev/docs/authentication

Lists tokens (prefix only).

```APIDOC
## GET /api/v1/me/api-tokens

### Description
Lists tokens (prefix only).

### Method
GET

### Endpoint
/api/v1/me/api-tokens

### Auth
- session

### Response
#### Success Response (200)
- List of API tokens (prefix only)

```

--------------------------------

### Run Postgres-backed tests with DATABASE_URL

Source: https://uptimepage.dev/docs/development

Set up a throwaway Postgres database and run the ignored Postgres-backed tests. The full ignored suite is slow; scope to a single test binary for faster iteration.

```bash
docker compose -f compose.dev.yml up -d
docker compose -f compose.dev.yml exec -T postgres createdb -U monitor ci_verify

# Whole ignored suite (slow — builds every test binary):
DATABASE_URL=postgres://monitor:monitor@127.0.0.1:5432/ci_verify \
  cargo test -- --ignored

# One suite (fast — scope to a binary; bare `nextest run` rebuilds +
# enumerates every integration test binary (about a hundred) and looks
# frozen for minutes):
DATABASE_URL=postgres://monitor:monitor@127.0.0.1:5432/ci_verify \
  cargo test --test status_page_settings_test -- --ignored --nocapture
```

--------------------------------

### GET /api/v1/me/sessions

Source: https://uptimepage.dev/docs/authentication

Lists active sessions.

```APIDOC
## GET /api/v1/me/sessions

### Description
Lists active sessions.

### Method
GET

### Endpoint
/api/v1/me/sessions

### Auth
- session

### Response
#### Success Response (200)
- List of active sessions

```

--------------------------------

### GET /api/v1/me

Source: https://uptimepage.dev/docs/authentication

Returns current user info.

```APIDOC
## GET /api/v1/me

### Description
Returns current user info.

### Method
GET

### Endpoint
/api/v1/me

### Auth
- session/token

### Response
#### Success Response (200)
- Current user information

```

--------------------------------

### Configure auth, email, and WhatsApp settings in config.toml

Source: https://uptimepage.dev/docs/configuration

Full TOML configuration for auth, email, and WhatsApp alerting. `auth.enabled_methods` is the policy switch per sign-in method: removing an entry disables that method's login start/callback (404) and hides its button. OAuth providers additionally need client_id + client_secret + redirect_url set — a listed but incompletely configured provider stays hidden and logs a warning on probe. `"magic_link"` mounts the magic-link request, verify and code endpoints along with the login-page email form. `auth.fingerprint_salt` is paired with the `auth_salt_history` table; rotating the value mid-deployment refuses to boot unless the override env var documented in `docs/troubleshooting.md` is set — deliberate so audit-trail breakage is loud.

```ini
[auth]
enabled_methods = ["github_oauth", "google_oauth", "microsoft_oauth", "gitlab_oauth", "magic_link"]
fingerprint_salt = ""                # HMAC salt for IP/UA hashes; rotate-aware
public_base_url = "https://status.example.test"

[auth.session]
idle_timeout_days = 30
absolute_timeout_days = 90
cookie_name = "_sm_session"
cookie_secure = true                 # set false only for plain-HTTP local dev
cookie_domain = ""                   # empty = host-only cookie
renew_on_use = true

[auth.github]
client_id = ""                       # from https://github.com/settings/developers
client_secret = ""
redirect_url = "https://status.example.test/auth/github/callback"
scopes = ["user:email", "read:user"]

[auth.google]
client_id = ""                       # Google Cloud Console OAuth web client
client_secret = ""
redirect_url = "https://status.example.test/auth/google/callback"
scopes = ["openid", "email", "profile"]

[auth.microsoft]
client_id = ""                       # Entra app registration (portal.azure.com)
client_secret = ""
redirect_url = "https://status.example.test/auth/microsoft/callback"
scopes = ["openid", "email", "profile"]
tenant = "common"                    # common | organizations | consumers | <tenant GUID or domain>

[auth.gitlab]
client_id = ""                       # GitLab application (User settings -> Applications)
client_secret = ""
redirect_url = "https://status.example.test/auth/gitlab/callback"
scopes = ["openid", "email", "profile"]
base_url = "https://gitlab.com"      # or a self-managed instance's https origin

[auth.invitations]
expiry_hours = 168                   # 7 days; pending-invite cap is plans.max_pending_invitations

[auth.api_tokens]
prefix_visible_chars = 16            # floor; lower values fail boot; per-user cap is plans.max_api_tokens_per_user

[auth.magic_link]
expiry_minutes = 15                  # covers the link and the code printed beside it
rate_limit_seconds = 60                # per-email send throttle; 0 disables

[email]
provider = "log"                     # "resend" in prod, "log" in dev, "memory" in tests
from_name = "Uptimepage"
from_address = "no-reply@example.test"
support_address = ""                 # set it and /help appears; empty = no help form

[email.resend]
api_key = ""                         # required when provider = "resend"
webhook_secret = ""                  # whsec_… of the Resend webhook endpoint

[whatsapp_app]                       # operator WhatsApp number (one-tap linking)
enabled = false                      # deliberate spend gate — creds alone stay off
access_token = ""                    # Meta Cloud API token (env-only)
phone_number_id = ""                 # Cloud API sender id
public_number = ""                   # display number digits — the wa.me target
app_secret = ""                      # signs webhook deliveries (env-only)
verify_token = ""                    # echoed by Meta's GET subscribe handshake
template_name = ""                   # approved alert template, single body param
language_code = "en"
copy
```

--------------------------------

### GET /auth/gitlab/callback

Source: https://uptimepage.dev/docs/authentication

Handles the OAuth callback from GitLab.

```APIDOC
## GET /auth/gitlab/callback

### Description
Handles the OAuth callback from GitLab.

### Method
GET

### Endpoint
/auth/gitlab/callback

### Response
#### Success Response (302)
- Redirect to the application after authentication

```

--------------------------------

### Configure trace export with observability.tracing_enabled and observability.grafana.enabled

Source: https://uptimepage.dev/docs/configuration

Configuration block for OpenTelemetry trace export over OTLP/HTTP (protobuf). Both tracing_enabled and grafana.enabled must be true to activate export; defaults are false and zero-cost when off. The api_key is never read from this file; it must be supplied via the UPTIMEPAGE_OBSERVABILITY__GRAFANA__API_KEY environment variable.

```toml
[observability]
tracing_enabled = false                # master on/off for trace export

[observability.grafana]
enabled = false                        # second switch; both must be true
otlp_endpoint = ""                     # OTLP base, no /v1/traces suffix; e.g.
                                       # https://otlp-gateway-<zone>.grafana.net/otlp
instance_id = ""                       # Grafana Cloud numeric instance / stack id
trace_sample_ratio = 0.05              # example override; shipped default is 1.0 (keep-all)
# api_key                              # NEVER in TOML — env var only (below)

```