Skip to main content

Convex Environments

Locked Decision​

VRDex keeps three Convex execution targets separate:

  • local development: anonymous local Convex from pnpm dev:backend:local or pnpm verify:backend:local
  • deployed smoke testing: the shared development Convex deployment
  • production release: the production Convex deployment

Current Deployments​

Do not commit deploy keys. Store them in GitHub/hosting secret stores and local ignored env files only.

Current recommendation: define environment variable names and target scopes in docs or IaC first, then set secret values through provider secret stores. Manual Convex dashboard edits should be treated as bootstrap/emergency changes and followed by a reproducibility update here or in automation.

  • development cloud URL: https://scrupulous-corgi-247.convex.cloud
  • production cloud URL: https://superb-pig-954.convex.cloud

GitHub Actions secret names:

  • CONVEX_DEPLOY_KEY_DEV: development deployment key
  • CONVEX_DEPLOY_KEY_PROD: production deployment key used by the main-branch deploy workflow

Local ignored env names:

  • CONVEX_DEPLOY_KEY_DEV
  • CONVEX_DEPLOY_KEY_PROD
  • CONVEX_URL_DEV
  • CONVEX_URL_PROD

Auth Email Environment​

Convex deployments that send password or email verification messages through SES must set:

  • AWS_SES_REGION
  • AWS_SES_FROM_EMAIL
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • VRDEX_APP_NAME optional display name

The hosted SES baseline is documented in docs/deployment/ses-auth-email.md and docs/deployment/aws-baseline.md. Store secret values in Convex env, never in git.

Hosted E2E Helpers​

Hosted mutation-backed Playwright runs use only the shared development/staging target. Do not enable these helpers in production.

Development/staging Convex env names:

  • VRDEX_ENABLE_E2E_HELPERS=true
  • VRDEX_E2E_CONVEX_SECRET: non-empty sentinel also configured in the hosted app environment
  • VRDEX_ENABLE_E2E_AUTH_HELPERS=true: optional, only when hosted auth/claim E2E is intentionally enabled
  • VRDEX_ENABLE_E2E_ADAPTER_HELPERS=true: optional, only when hosted adapter E2E is intentionally enabled
  • SITE_URL=https://staging.vrdex.net: required by Convex Auth email/password redirects for hosted auth E2E
  • JWT_PRIVATE_KEY: Convex Auth RS256 private key, generated for the shared development deployment and never printed
  • JWKS: Convex Auth public key set matching JWT_PRIVATE_KEY
  • DISCORD_API_BASE_URL: optional hosted adapter stub base URL, usually https://staging.vrdex.net/api/e2e/adapters/discord
  • DISCORD_BOT_TOKEN: staging-only adapter token matching the hosted app environment
  • VRCHAT_PROOF_ADAPTER_URL: optional hosted adapter stub URL, usually https://staging.vrdex.net/api/e2e/adapters/vrchat-proof
  • VRCLINKING_PROOF_ADAPTER_URL: optional hosted adapter stub URL, usually https://staging.vrdex.net/api/e2e/adapters/vrchat-proof
  • VRCHAT_PROOF_ADAPTER_BEARER_TOKEN: staging-only adapter token matching the hosted app environment

The browser-facing token stays in the web host and GitHub Actions as VRDEX_E2E_BROWSER_TOKEN / VRDEX_HOSTED_E2E_BROWSER_TOKEN; it is not needed by Convex.

The shared development deployment scrupulous-corgi-247 is the current hosted E2E backend for Vercel staging. The Staging Deploy GitHub Actions workflow deploys Convex development functions with CONVEX_DEPLOY_KEY_DEV before deploying Vercel staging and running hosted data-flow health.

Generate Convex Auth JWT keys through a non-printing command path and set them with convex env set -- NAME VALUE, because PEM values begin with dashes and can be parsed as CLI options if passed in the wrong position.

Manual fallback if the workflow is unavailable:

$env:CONVEX_DEPLOYMENT="dev:scrupulous-corgi-247"; $env:CONVEX_SELF_HOSTED_URL=""; pnpm exec convex dev --once --typecheck=try --tail-logs=disable

Custom Domain Plan​

Candidate direction: use readable Convex Cloud custom domains once the deployment settings are configured in the Convex dashboard:

  • development/staging Convex API: convex.staging.vrdex.net
  • production Convex API: convex.vrdex.net

Convex Cloud custom domains are configured from each deployment's dashboard settings and require a Convex Pro plan. Do not create Route 53 records alone; Convex must first provide the deployment-specific DNS records and certificate binding.

Runbook once Convex Pro is enabled:

  1. In the Convex dashboard for scrupulous-corgi-247, request convex.staging.vrdex.net as the development/staging custom domain.
  2. In the Convex dashboard for superb-pig-954, request convex.vrdex.net as the production custom domain.
  3. Copy the exact DNS records Convex provides into Route 53 for the public hosted zone vrdex.net.
  4. Wait for Convex certificate/domain status to become active.
  5. Update the matching Vercel environment NEXT_PUBLIC_CONVEX_URL and CONVEX_URL values.
  6. Rerun Staging Deploy for staging and deployed health for production.

Notes​

There are two similarly named Convex projects in the account history: vrdex and vrdex-85631. Current recommendation is to keep the vrdex line of deployments and archive/delete the other only after confirming no dashboard, env, or deployment history still depends on it.