What you are hosting
Your database supports Your issuer application. Credential payloads remain encrypted and stored in DStorage.
Running Postgres yourself is optional. The issuer service needs a connection string for
DATABASE_URL in order to store responses.Choose a path
Prerequisites
- A GitHub account (to deploy
air-issuer-service) - An AIR Developer Dashboard Partner ID
- Issuer secrets ready (or generate them during setup):
SEED, Partner JWT private key,API_KEY,ADMIN_API_KEY— see Partner authentication and the issuance quickstart
Recommended path: Railway (backend + Postgres)
1
Create a Railway project
Sign up at railway.com and create a new project.
2
Deploy the issuer service
In the project canvas, click + New → GitHub Repo and deploy
Forked Air Issuer Service.Set the service commands under Settings → Deploy:The pre-deploy command applies MikroORM migrations before each new version starts. See Railway’s pre-deploy command docs.
3
Add PostgreSQL
Click + New → Database → PostgreSQL. Railway provisions the database in the same project.
4
Wire DATABASE_URL
On the issuer service, open Variables and add a reference variable:Use the exact Postgres service name shown in your project if it differs from
Postgres.5
Configure issuer secrets
Add the remaining server-side variables on the issuer service:Railway injects
PORT automatically. The NestJS service must listen on process.env.PORT (the starter already does).Store secrets in Railway Variables or a secrets manager — never commit them. See the security checklist.6
Generate a public HTTPS domain
On the issuer service, open Settings → Networking → Public Networking and click Generate Domain.Copy the No trailing slash.
https://…up.railway.app URL (or your custom domain) and set:ISSUER_ORIGIN is embedded in credential status URLs, so it must match the public origin that serves /credential-status/:nonce.7
Verify the deployment
After the deploy succeeds:Expect HTTP Then fetch the issuer DID:
200 with healthy checks:When
/ready reports status: "ready" over public HTTPS, your sandbox backend and database are hosted. Continue with issuer activation and schema setup in Quickstart 2: Credential issuance.Railway Free plan caveats
- After the trial, Free includes $1 of usage credit per month (does not roll over). If usage exceeds the credit, Railway stops workloads until the next monthly reset — you may need to redeploy manually.
- Free plan caps are small (for example, 0.5 GB RAM / 1 vCPU per service). Keep the issuer lean for sandbox.
- Official references: Railway plans, Free Trial.
Alternatives
Database only
Use these when you already have a place to run the NestJS process (or a tunnel for local development) and only need Postgres.
Copy the Postgres connection string into
DATABASE_URL on your issuer backend, then run migrations:
Backend only
Use these when Postgres already lives elsewhere (for example Neon or Supabase).
Point
DATABASE_URL at your external Postgres, set ISSUER_ORIGIN to the public HTTPS hostname the host assigns, and use the same build / start / migrate commands as the Railway walkthrough.
After hosting: AIR readiness checklist
Hosting the backend is not enough for credential flows. Complete these next:- Register the issuer with AIR — Issuer DID,
API_KEY, and Partner ID. See issuing credentials and the issuance quickstart. - Publish JWKS over HTTPS — Required for
issueCredential/verifyCredential. Often hosted on your web app (Vercel, Netlify, etc.), not necessarily on the issuer service. See JWKS endpoint setup. - Keep secrets server-side — Partner private key,
SEED, and API keys never ship to the browser. See Partner authentication and the security checklist. - Whitelist domains — Add your web app origin in the Developer Dashboard under Account → Domains.
Local development
For local work, run Postgres on your machine (or use Neon/Supabase) and expose the issuer with an HTTPS tunnel so AIR can reach status endpoints and JWKS:- ngrok, zrok or cloudflared — full procedure on JWKS endpoint setup
ISSUER_ORIGIN to the tunnel HTTPS origin while testing.
Next steps
Credential issuance quickstart
Configure schemas, Partner JWT, and the SDK issuance flow.
JWKS endpoint setup
Publish and register the public JWKS URL credential calls require.
Issuing credentials
Issuer backend model and server-side issuance.
Security checklist
JWT, secrets, and API hardening for partner integrations.