Skip to content

Commit 7ad89df

Browse files
nayan-kunwarnayan-kunwar
committed
fix: db url issue
1 parent 55effb7 commit 7ad89df

15 files changed

Lines changed: 748 additions & 6 deletions

File tree

‎.env.example‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,5 @@ CORS_ORIGINS=http://localhost:3000
1212

1313
# Dev can use Neon/Upstash in .env — but integration tests always override to
1414
# local Docker (tests/setup.ts). See .env.test. Never run tests against cloud DB.
15+
#
16+
# Full env guide: notes/env/README.md

‎.env.production.example‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Copy values into Render Dashboard → Environment (do not commit real secrets).
2+
# Keep your private copy as .env.production (gitignored).
3+
4+
NODE_ENV=production
5+
DATABASE_URL=postgresql://USER:[email protected]/neondb?sslmode=verify-full
6+
REDIS_URL=rediss://default:[email protected]:6379
7+
API_KEYS=your-strong-production-api-key
8+
DEMO_ENABLED=true
9+
SIGNUP_ENABLED=true
10+
SESSION_COOKIE_NAME=payonce_session
11+
SESSION_TTL_HOURS=168
12+
IDEMPOTENCY_TTL_SECONDS=86400
13+
CORS_ORIGINS=https://your-app.onrender.com

‎.gitignore‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,4 @@ project-context.md
3939
improvement-ideas.md
4040
next-task.md
4141

42-
# personal project notes (local only)
43-
notes/
4442
.cursor/

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,9 @@ drizzle/
209209

210210
## Environment Variables
211211

212-
See [.env.example](./.env.example) for all options.
212+
Full guide: [notes/env/README.md](./notes/env/README.md) (files, profiles, Render checklist).
213+
214+
See [.env.example](./.env.example) for a local Docker template and [.env.production.example](./.env.production.example) for Render (placeholders only).
213215

214216
| Variable | Description |
215217
|----------|-------------|

‎notes/README.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# PayOnce notes
2+
3+
Informal docs and runbooks (complement [docs/](../docs/README.md)).
4+
5+
## Environment variables
6+
7+
| Note | Description |
8+
|------|-------------|
9+
| [env/README.md](./env/README.md) | **All env files** — `.env`, `.env.local`, `.env.production`, variables, profiles |
10+
11+
## Render (production)
12+
13+
| Note | Description |
14+
|------|-------------|
15+
| [how-latest-code-is-deployed.md](./render/how-latest-code-is-deployed.md) | **How Render deploys the latest code** — CI → GHCR → Deploy Hook |
16+
| [split-stack.md](./render/split-stack.md) | Render + Neon + Upstash setup |
17+
18+
## GitHub Actions
19+
20+
| Note | Description |
21+
|------|-------------|
22+
| [ci.yml.md](./github-actions/ci.yml.md) | CI workflow |
23+
| [deploy.yml.md](./github-actions/deploy.yml.md) | CD workflow (GHCR + Render hook) |
24+
25+
## Other
26+
27+
| Note | Description |
28+
|------|-------------|
29+
| [api-keys/README.md](./api-keys/README.md) | API key notes |

‎notes/api-keys/README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# API keys
2+
3+
**Config:** `API_KEYS` env var in `.env` / Render / Fly secrets
4+
**Code:** `src/middleware/apiKeyAuth.ts`, `src/config/env.ts`
5+
6+
## What they are
7+
8+
Shared secrets that clients must send to use the **payment API**. Think of them as passwords for `/api/v1/*` routes.
9+
10+
Without a valid key, requests get **401 Unauthorized**.
11+
12+
## What they protect
13+
14+
| Route | API key required? |
15+
|-------|-------------------|
16+
| `GET /` | No |
17+
| `GET /health` | No |
18+
| `GET /ready` | No |
19+
| `POST /api/v1/payments` | **Yes** |
20+
| `GET /api/v1/payments` | **Yes** |
21+
| `GET /api/v1/payments/:id` | **Yes** |
22+
| `PATCH /api/v1/payments/:id/status` | **Yes** |
23+
24+
Health routes stay public so Render/Fly can probe `/ready` without a key.
25+
26+
## How clients send the key
27+
28+
Either header works:
29+
30+
```
31+
Authorization: Bearer your-api-key
32+
```
33+
34+
or
35+
36+
```
37+
X-API-Key: your-api-key
38+
```
39+
40+
## Configuration
41+
42+
`API_KEYS` is a **comma-separated** list in env:
43+
44+
```env
45+
API_KEYS=dev-api-key,another-dev-key
46+
```
47+
48+
Parsed in `src/config/env.ts` — split by comma, trimmed, empty values removed.
49+
50+
| Environment | Example |
51+
|-------------|---------|
52+
| Local | `dev-api-key` (`.env.example`) |
53+
| CI | `test-api-key` (`.github/workflows/ci.yml`) |
54+
| Production (Render) | Strong random secret — **not** `dev-api-key` |
55+
56+
## Example requests
57+
58+
```bash
59+
# List payments — works with valid key
60+
curl -H "Authorization: Bearer your-api-key" \
61+
https://payonce-uppq.onrender.com/api/v1/payments
62+
63+
# Missing key — 401
64+
curl https://payonce-uppq.onrender.com/api/v1/payments
65+
66+
# Create payment
67+
curl -X POST https://payonce-uppq.onrender.com/api/v1/payments \
68+
-H "Content-Type: application/json" \
69+
-H "Authorization: Bearer your-api-key" \
70+
-H "Idempotency-Key: unique-key-123" \
71+
-d '{"amount": 1000, "customerId": "cust_123"}'
72+
```
73+
74+
## Why it matters in production
75+
76+
The API is on a **public URL**. API keys stop strangers from:
77+
78+
- Creating fake payments
79+
- Reading payment data
80+
- Updating payment status
81+
82+
This is **shared-secret auth** — simple, not user login. Good for server-to-server or trusted clients (your app, Postman, scripts).
83+
84+
## Multiple keys
85+
86+
Use several keys for different clients:
87+
88+
```env
89+
API_KEYS=mobile-app-key,admin-key,partner-key
90+
```
91+
92+
Rotate or revoke one key without breaking others.
93+
94+
## Flow (middleware)
95+
96+
```
97+
Request → extract key from Authorization or X-API-Key
98+
→ compare against env.API_KEYS[]
99+
→ match? continue to route handler
100+
→ no match? 401 UnauthorizedError
101+
```
102+
103+
Applied on all routes in `src/routes/PaymentRoutes.ts` via `router.use(apiKeyAuth)`.
104+
105+
## Notes
106+
107+
_Add your own notes below — key rotation, Render env setup, generating secrets, etc._

‎notes/env/README.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
# Environment variables
2+
3+
PayOnce reads configuration from `process.env`, validated in [`src/config/env.ts`](../../src/config/env.ts) with Zod.
4+
5+
Bun loads dotenv files automatically when you run `bun run dev` or `bun run start`.
6+
7+
## Files in this repo
8+
9+
| File | Committed? | Purpose |
10+
|------|------------|---------|
11+
| [`.env.example`](../../.env.example) | Yes | Template for new developers — **local Docker** Postgres + Redis |
12+
| [`.env.test`](../../.env.test) | Yes | Reference values for tests (overridden by [`tests/setup.ts`](../../tests/setup.ts)) |
13+
| `.env` | No | **Active local config** — what `bun run dev` uses on your machine |
14+
| `.env.local` | No | Optional personal dev file (e.g. Neon + Upstash while app runs on localhost) |
15+
| `.env.production` | No | Private checklist of **Render production** values — paste into Render Dashboard, do not deploy as a file |
16+
17+
Never commit `.env`, `.env.local`, or `.env.production` — they contain secrets.
18+
19+
## Which file should I use?
20+
21+
| Scenario | What to do |
22+
|----------|------------|
23+
| First clone | `cp .env.example .env` then `docker compose up -d postgres redis` and `bun run migrate` |
24+
| Local dev with Docker only | Keep `.env.example` values in `.env` |
25+
| Local dev with cloud DB (Neon/Upstash) | Put Neon/Upstash URLs in `.env` or `.env.local` |
26+
| Production on Render | Set variables in **Render → Environment** (use `.env.production` as your private checklist) |
27+
| Integration tests | Safe even if `.env` points at Neon — [`tests/setup.ts`](../../tests/setup.ts) redirects cloud URLs to local Docker |
28+
29+
## Variable reference
30+
31+
| Variable | Required | Default | Description |
32+
|----------|----------|---------|-------------|
33+
| `PORT` | No | `3000` | HTTP port. Render sets this automatically (e.g. `10000`). |
34+
| `NODE_ENV` | No | `development` | `development`, `production`, or `test` |
35+
| `DATABASE_URL` | **Yes** | — | PostgreSQL connection string |
36+
| `REDIS_URL` | No | `redis://localhost:6379` | Redis or Upstash URL (`redis://` or `rediss://`) |
37+
| `API_KEYS` | No | `dev-api-key` | Comma-separated server API keys (see below) |
38+
| `DEMO_ENABLED` | No | `true` | Set `false` to disable `/demo/api` |
39+
| `SIGNUP_ENABLED` | No | `true` | Set `false` to disable public `POST /api/keys` |
40+
| `SESSION_COOKIE_NAME` | No | `payonce_session` | HttpOnly session cookie for `/auth` and `/dashboard` |
41+
| `SESSION_TTL_HOURS` | No | `168` | Session lifetime in hours (7 days) |
42+
| `IDEMPOTENCY_TTL_SECONDS` | No | `86400` | How long idempotency records are kept (24 hours) |
43+
| `CORS_ORIGINS` | No | (empty) | Comma-separated browser origins. Empty = allow all in dev; restrict in production |
44+
45+
Optional overrides used only during tests:
46+
47+
| Variable | Purpose |
48+
|----------|---------|
49+
| `TEST_DATABASE_URL` | Force a specific Postgres URL for integration tests |
50+
| `TEST_REDIS_URL` | Force a specific Redis URL for integration tests |
51+
52+
## Environment profiles
53+
54+
### Profile A — Local Docker (`.env.example`)
55+
56+
Best for offline dev and matching CI/local test defaults.
57+
58+
```env
59+
PORT=3000
60+
NODE_ENV=development
61+
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/payonce
62+
REDIS_URL=redis://localhost:6379
63+
API_KEYS=dev-api-key,another-dev-key
64+
DEMO_ENABLED=true
65+
SIGNUP_ENABLED=true
66+
SESSION_COOKIE_NAME=payonce_session
67+
SESSION_TTL_HOURS=168
68+
IDEMPOTENCY_TTL_SECONDS=86400
69+
CORS_ORIGINS=http://localhost:3000
70+
```
71+
72+
Requires:
73+
74+
```bash
75+
docker compose up -d postgres redis
76+
bun run migrate
77+
bun run dev
78+
```
79+
80+
Postgres is on host port **5433** (not 5432) to avoid clashing with a local Postgres install.
81+
82+
### Profile B — Local app + cloud data (`.env.local` pattern)
83+
84+
Run the app on `http://localhost:3000` but store data in Neon and Upstash:
85+
86+
```env
87+
PORT=3000
88+
NODE_ENV=development
89+
DATABASE_URL=postgresql://USER:[email protected]/neondb?sslmode=require
90+
REDIS_URL=rediss://default:[email protected]:6379
91+
API_KEYS=dev-api-key,another-dev-key
92+
DEMO_ENABLED=true
93+
SIGNUP_ENABLED=true
94+
SESSION_COOKIE_NAME=payonce_session
95+
SESSION_TTL_HOURS=168
96+
IDEMPOTENCY_TTL_SECONDS=86400
97+
CORS_ORIGINS=http://localhost:3000
98+
```
99+
100+
Use Neon’s **pooled** connection string. Wrap `REDIS_URL` in quotes if the value contains special characters.
101+
102+
### Profile C — Production Render (`.env.production` checklist)
103+
104+
Set these in **Render Dashboard → Environment**, not as a file on the server:
105+
106+
```env
107+
NODE_ENV=production
108+
DATABASE_URL=postgresql://[email protected]/neondb?sslmode=require
109+
REDIS_URL=rediss://[email protected]:6379
110+
API_KEYS=your-strong-production-key
111+
DEMO_ENABLED=true
112+
SIGNUP_ENABLED=true
113+
SESSION_COOKIE_NAME=payonce_session
114+
SESSION_TTL_HOURS=168
115+
IDEMPOTENCY_TTL_SECONDS=86400
116+
CORS_ORIGINS=https://your-app.onrender.com
117+
```
118+
119+
Replace `CORS_ORIGINS` with your real Render URL (and any other front-end origins you allow).
120+
121+
`PORT` is injected by Render — do not hardcode it unless debugging.
122+
123+
## Two kinds of API keys
124+
125+
| Type | Stored in | Used for |
126+
|------|-----------|----------|
127+
| **Env keys** | `API_KEYS` variable | Server-configured keys; work without dashboard signup |
128+
| **Personal keys** | Neon `api_keys` table | Created at `/dashboard`; format `pk_live_…` |
129+
130+
Both authenticate `/api/v1` via `Authorization: Bearer <key>`.
131+
132+
Env keys survive database resets. Personal keys are lost if the `api_keys` table is truncated (e.g. accidental test run against cloud DB before the test safety guards).
133+
134+
For Scalar `/docs` Try It, env keys like `pk_live_dev_payonce_scalar01` work without creating a dashboard key.
135+
136+
## GitHub secret (not app env)
137+
138+
| Secret | Where | Purpose |
139+
|--------|-------|---------|
140+
| `RENDER_DEPLOY_HOOK` | GitHub → Settings → Secrets → Actions | CD workflow POSTs here after pushing `:latest` to GHCR |
141+
142+
See [../render/how-latest-code-is-deployed.md](../render/how-latest-code-is-deployed.md).
143+
144+
## How Bun loads env files
145+
146+
Typical load order (later overrides earlier):
147+
148+
1. `.env`
149+
2. `.env.local`
150+
3. `.env.[NODE_ENV]` (e.g. `.env.development`)
151+
4. `.env.[NODE_ENV].local`
152+
153+
Keep one active source of truth (usually `.env`) to avoid confusion.
154+
155+
## Integration tests and your `.env`
156+
157+
[`tests/setup.ts`](../../tests/setup.ts) runs before integration tests:
158+
159+
- If `DATABASE_URL` or `REDIS_URL` points at a **cloud host** (Neon, Upstash, etc.), tests switch to **local Docker** URLs.
160+
- If URLs are already local (e.g. CI on `localhost:5432`), they are kept unchanged.
161+
162+
[`tests/helpers/testUtils.ts`](../../tests/helpers/testUtils.ts) refuses to `TRUNCATE` or `flushdb` remote URLs as a second safety net.
163+
164+
Never disable these guards when pointing at production data.
165+
166+
## Common mistakes
167+
168+
| Mistake | Result |
169+
|---------|--------|
170+
| Committing `.env.local` / `.env.production` | Leaked database and Redis credentials |
171+
| Wrong `CORS_ORIGINS` in production | Browser blocks API calls from your site |
172+
| Using only the key **prefix** from the dashboard table | 401 — full secret is shown once at creation |
173+
| Pinning Render GHCR image to an old SHA | Production never updates when CD publishes `:latest` |
174+
175+
## Related docs
176+
177+
- [`.env.example`](../../.env.example) — committed template
178+
- [`.env.test`](../../.env.test) — test reference
179+
- [docs/09-deployment-and-devops](../../docs/09-deployment-and-devops/README.md) — Render env setup
180+
- [docs/08-testing](../../docs/08-testing/README.md) — test env overrides
181+
- [../api-keys/README.md](../api-keys/README.md) — API key types

0 commit comments

Comments
 (0)