Production

Deploy AppMetricsKit with explicit health, readiness, and smoke checks.

Use this checklist before pointing SDKs and payment webhooks at the production domain.

Required environment

Launch with Convex-only event storage. The readiness endpoint validates configuration and confirms that Convex identifies as production and reports the configured deployment URL. It never returns secret values.

The production environment check also retrieves the configured Stripe Customer Portal and requires an active live configuration with customer updates, invoices, payment methods, and cancellation enabled.

APP_BASE_URL=https://appmetricskit.comSITE_URL=https://appmetricskit.comAUTH0_SECRETAUTH0_DOMAINAUTH0_CLIENT_IDAUTH0_CLIENT_SECRETNEXT_PUBLIC_CONVEX_URLAMK_DEPLOYMENT_ENVIRONMENT=production (web and Convex)STRIPE_SECRET_KEYNEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYSTRIPE_WEBHOOK_SECRETSTRIPE_SYNC_SECRETSTRIPE_PRICE_INDIESTRIPE_PRICE_GROWTHSTRIPE_PRICE_SCALESTRIPE_TEST_PRICE_INDIESTRIPE_TEST_PRICE_GROWTHSTRIPE_TEST_PRICE_SCALESTRIPE_CHECKOUT_SUCCESS_URLSTRIPE_CHECKOUT_CANCEL_URLSTRIPE_BILLING_PORTAL_CONFIGURATION_IDSTRIPE_BILLING_PORTAL_RETURN_URLPROVIDER_WEBHOOK_SYNC_SECRETPROVIDER_SECRET_ENCRYPTION_KEY (Convex only)KEY_PEPPER (Convex only)EVENT_STORAGE_MODE=convex

Runtime endpoints

/api/health

Use for uptime monitoring. Returns 200 when the Next.js app is alive.

/api/ready

Use before release. Returns 503 until required production variables are valid and Convex is reachable.

/api/webhooks/stripe

Stripe webhook destination: https://appmetricskit.com/api/webhooks/stripe

/api/internal/clickhouse/flush

Optional protected retry endpoint used only after the ClickHouse dual-write migration.

Release commands

Run these locally or with the manually triggered Production verification workflow after publishing the SDKs and deploying production. The browser check performs a real Auth0 login, and the guarded load script requires a test-app ingest key.

Code

npx convex env set --prod AMK_DEPLOYMENT_ENVIRONMENT productionnpx convex deploy
# Configure the web deployment with the production URL printed above, then:npm run check:prod-envnpm run check:sdk-releasesnpm run buildSMOKE_BASE_URL=https://appmetricskit.com npm run smoke
# Authenticated browser verification with a dedicated Auth0 test userE2E_BASE_URL=https://appmetricskit.com \E2E_AUTH_EMAIL=tester@example.com \E2E_AUTH_PASSWORD=... \npm run test:e2e
# After 1,000 active users, optional ClickHouse dual-write migration:# set EVENT_STORAGE_MODE=dual and the optional warehouse variables, then# schedule the retry endpoint:curl -X POST https://appmetricskit.com/api/internal/clickhouse/flush \  -H "Authorization: Bearer $CRON_SECRET"
# Optional ingest load check against a test app/keyLOAD_BASE_URL=https://appmetricskit.com \AMK_LOAD_INGEST_KEY=amk_test_... \npm run load:ingest -- --rate 100 --seconds 60 --batch-size 50 --confirm-production

Optional warehouse after 1,000 active users

Keep these unset at launch. Add ClickHouse only when event volume, query latency, or Convex storage cost justifies it, then migrate through dual-write mode. The events table must use ReplacingMergeTree(ingested_at); readiness rejects a legacy plain MergeTree. Analytics and exports read with FINAL so retries cannot inflate counts before ClickHouse merges duplicate outbox rows.

CLICKHOUSE_URLCLICKHOUSE_USERNAMECLICKHOUSE_PASSWORDCLICKHOUSE_DATABASE=appmetricskitCLICKHOUSE_EVENTS_TABLE=events_rawCLICKHOUSE_REQUEST_TIMEOUT_MS=10000INGEST_STORAGE_SYNC_SECRETCRON_SECRET

External dashboard setup

Auth0

- Allowed callback: https://appmetricskit.com/auth/callback
- Allowed logout: https://appmetricskit.com/
- Set APP_BASE_URL to the same HTTPS origin.

Stripe

- Webhook endpoint: https://appmetricskit.com/api/webhooks/stripe
- Events: checkout.session.completed, customer.subscription.*, invoice.payment_*
- Set the same dedicated STRIPE_SYNC_SECRET in Next.js and Convex; never reuse the webhook signing secret.

Raw events

- Launch with EVENT_STORAGE_MODE=convex; no ClickHouse account or cron is required.
- Review event volume, query latency, and storage cost near 1,000 active users.
- When needed, migrate to EVENT_STORAGE_MODE=dual before considering a warehouse-only architecture.

Monitoring

- Ping /api/health every minute.
- Alert on /api/ready failures during release validation.
- Use /exports and scheduled destination configs for backup/export policy.

Continue setup

After deployment, install the SDK in a test app and verify events in Live Events.

Open test-mode guide