Self-hosting guide

QRdx is AGPL-3.0 licensed, and you can run the whole web app (QR editor, accounts, saved themes, community gallery and these docs) on your own server. You don't need any of this to use the qrdx React library or the CLI. Those run anywhere without a backend.

Requirements

• Docker with Compose v2, or Node.js 20+ and pnpm 10 for the manual setup
• A GitHub or Google OAuth app. Sign-in is OAuth-only, so you need at least one provider to create accounts.
• Postgres: the container bundled in docker-compose.yml, or a Neon database

How the database connection works

The app talks to Postgres through Neon's serverless HTTP driver.

• Neon: works directly. Set DATABASE_URL to your Neon connection string.
• Plain Postgres: needs a Neon-compatible HTTP proxy in front of it. docker-compose.yml runs one (local-neon-http-proxy) and sets DATABASE_HTTP_ENDPOINT so the app sends its queries there.

The schema comes from packages/database/schema.ts and is applied with drizzle-kit push.

Quick start with Docker Compose

git clone https://github.com/bucharitesh/qrdx.git
cd qrdx

cp .env.example .env

docker compose up -d --build

docker compose ps                    # migrate should show "exited (0)"
docker compose logs -f migrate app   # follow the schema sync and the app

ADMIN_EMAILS=you@example.com

docker compose up -d app

Using Neon or another managed database

You can skip the bundled Postgres and run only the app image:

docker build -t qrdx --build-arg NEXT_PUBLIC_APP_URL=https://qr.example.com .
docker run -d --env-file .env -p 3000:3000 qrdx

Set DATABASE_URL in .env to your Neon connection string and leave DATABASE_HTTP_ENDPOINT unset. Apply the schema once (and again after each update) with the migrator image:

docker build --target migrator -t qrdx-migrate .
docker run --rm -e DATABASE_URL="<your connection string>" qrdx-migrate

Manual setup (Node.js)

git clone https://github.com/bucharitesh/qrdx.git
cd qrdx
pnpm install

cp .env.example apps/docs/.env.local                    # then edit it
echo 'DATABASE_URL=<your connection string>' > packages/database/.env

pnpm db:push                                             # apply the schema
pnpm --filter docs dev                                   # http://localhost:3000

For production, build and start the app:

pnpm turbo build --filter=docs
pnpm --filter docs start

pnpm db:push connects with Neon's driver, so it needs a Neon database. To use the Docker Postgres for local development instead, start it with docker compose up -d db db-proxy, apply the schema with docker compose run --rm migrate, and set these in apps/docs/.env.local:

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/qrdx
DATABASE_HTTP_ENDPOINT=http://localhost:4444/sql

Environment variables

.env.example lists every variable with a short note on where to get it.

Minimum

Add one OAuth provider (GitHub or Google) so people can sign in.

Optional services

INTEGRATION_ENCRYPTION_KEY must be set in production as soon as you enable an integration, because it encrypts the stored tokens.

Reverse proxy and HTTPS

Put the app behind a reverse proxy such as Caddy, nginx or Traefik that terminates TLS, and don't expose port 3000 to the internet directly. Rate limiting reads the client IP from X-Real-IP and then X-Forwarded-For, so the proxy must set these headers and the app must only be reachable through it.

Once HTTPS is set up, change NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL to the https:// URL, update the OAuth callback URLs, and rebuild.

Updating

Back up the database first:

docker compose exec db pg_dump -U postgres qrdx > qrdx-backup.sql

Then pull and rebuild. The migrate service syncs the schema again before the app starts.

git pull
docker compose up -d --build

For the manual setup, run git pull, pnpm install and pnpm db:push, then rebuild.

If a schema change would drop data, drizzle-kit push asks for confirmation. In that case, run docker compose run --rm migrate in a terminal to review and confirm the changes.

Troubleshooting

• "Invalid environment variables" on startup: the log names each missing or invalid variable. Optional variables must be commented out, not set to an empty value.
• "BETTER_AUTH_SECRET is missing" or "You are using the default secret": set BETTER_AUTH_SECRET and recreate the container.
• OAuth redirect_uri mismatch: the callback URL in your OAuth app must be exactly <NEXT_PUBLIC_APP_URL>/api/auth/callback/<github|google>. Set BETTER_AUTH_URL to the same base URL.
• App can't reach the database (fetch failed): with plain Postgres, DATABASE_HTTP_ENDPOINT must point at the running proxy. Check docker compose ps db-proxy.
• migrate never finishes: drizzle-kit push is waiting for a confirmation. See Updating.
• A changed NEXT_PUBLIC_* value has no effect: rebuild the image.
• Port 4444 is already in use: change the db-proxy port mapping in docker-compose.yml. Only local development on the host uses it.