useGrant

Self-hosting

Run useGrant on your own infrastructure with Docker Compose.

useGrant is open source under the Apache License 2.0 and can run anywhere Docker runs. The bundled Docker Compose setup starts four services:

  • postgres: the PostgreSQL database
  • migrate: applies database migrations, then exits
  • app: the useGrant web app and API, on port 3000
  • cron: calls the app's cron endpoint every two hours to remove expired sessions and rotate signing keys

Requirements

  • Docker with Docker Compose
  • A domain for the app and a domain for provider issuer URLs, both served over HTTPS
  • A reverse proxy or load balancer that terminates TLS in front of port 3000

Relying parties such as AWS and Google Cloud only trust issuers served over HTTPS with a valid certificate.

1. Clone the repository

git clone https://github.com/usegranthq/app.git usegrant
cd usegrant

2. Configure the environment

cp .env.example .env

Fill in .env. All variables are required unless marked optional.

VariableDescription
SITE_URLPublic URL of the app, for example https://usegrant.example.com
PROVIDER_DOMAINDomain of provider issuer URLs. A provider's issuer URL is https://<PROVIDER_DOMAIN>/<urlId>
DATABASE_URLPostgreSQL connection string, for example postgresql://usegrant:<password>@postgres:5432/usegrant
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DBCredentials for the bundled PostgreSQL container, matching DATABASE_URL
BETTER_AUTH_SECRETRandom secret used to sign sessions
JWT_SIGNING_SECRETRandom secret used to sign the email verification cookie
STATE_HMAC_SECRET_KEYRandom secret
CRON_SECRETRandom secret the cron service sends to the cron endpoint
OAUTH_GITHUB_APP_CLIENT_ID, OAUTH_GITHUB_APP_CLIENT_SECRETGitHub OAuth app for sign-in
OAUTH_GOOGLE_APP_CLIENT_ID, OAUTH_GOOGLE_APP_CLIENT_SECRETGoogle OAuth client for sign-in
TURNSTILE_SITE_KEY, TURNSTILE_SECRET_KEYCloudflare Turnstile keys for the login captcha
EMAIL_FROMSender address for login emails
RESEND_API_KEYResend API key, used to send emails in production
NODEMAILER_SMTP_URLSMTP URL, used to send emails in development
CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_IDCloudflare for SaaS credentials, used to provision custom domains
OTEL_DOMAIN, OTEL_API_TOKEN, OTEL_AXIOM_DATASETOpenTelemetry export to Axiom
INVITE_TOKENOptional. When set, only visitors with the invite token can sign up
DOCS_URLOptional. URL of a docs deployment to serve under /docs

Generate random secrets with openssl rand -base64 32.

3. Build the image

The build reads .env, so configure it first.

docker build -t usegrant .

4. Start the services

DOCKER_REPOSITORY=usegrant docker compose up -d

Compose waits for the database, runs the migrations, then starts the app and the cron service. The app listens on port 3000. Point your reverse proxy at it for both SITE_URL and PROVIDER_DOMAIN.

Reverse proxy

The proxy must forward the original host in the X-Forwarded-Host header. useGrant uses it to serve provider discovery documents and signing keys under PROVIDER_DOMAIN. Caddy and Traefik send it by default, with nginx add proxy_set_header X-Forwarded-Host $host;.

5. Use your instance

  • The dashboard is served at SITE_URL.
  • The REST API is served under /api/sdk, for example https://usegrant.example.com/api/sdk/v1/providers.
  • The OpenAPI specification is at /api/sdk/open-api.json.

Follow the quickstart with your instance's API URL to issue your first token.

Updating

Pull the latest changes, rebuild the image and restart. Migrations run automatically on start.

git pull
docker build -t usegrant .
DOCKER_REPOSITORY=usegrant docker compose up -d

On this page