Skip to content

Commit abda25b

Browse files
max-ltmax-lt
committed
Add environment variables documentation to README
Add env vars table, system tokens, shared storage and email sections. Remove duplicate table from DEPLOY.md, link to README instead.
1 parent fb762a0 commit abda25b

2 files changed

Lines changed: 55 additions & 31 deletions

File tree

‎DEPLOY.md‎

Lines changed: 6 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,8 @@ Create the environment **before** the first upload so the project inherits it au
9494

9595
## Environment variables
9696

97+
See [README.md](./README.md#environment-variables) for the full list of environment variables.
98+
9799
Secrets are prompted interactively (masked input) when value is omitted:
98100

99101
```bash
@@ -104,29 +106,9 @@ ow <space> env set openworkers-api-env APP_URL https://dash.example.com
104106
ow <space> env set openworkers-api-env JWT_ACCESS_SECRET --secret
105107
```
106108

107-
| Variable | Type | Required | Description |
108-
| ---------------------------------- | ------- | -------- | ---------------------------------------- |
109-
| `DATABASE` | binding | yes | Database binding (type: database) |
110-
| `ASSETS` | binding | yes | Assets storage binding (SvelteKit files) |
111-
| `APP_URL` | var | yes | Dashboard URL (for OAuth redirects) |
112-
| `POSTGATE_SYSTEM_TOKEN_SECRET` | secret | yes | System token HMAC secret (>= 32 chars) |
113-
| `JWT_ACCESS_SECRET` | secret | yes | JWT signing secret (>= 32 chars) |
114-
| `JWT_REFRESH_SECRET` | secret | yes | JWT refresh token secret (>= 32 chars) |
115-
| `GITHUB_CLIENT_ID` | var | no | GitHub OAuth app client ID |
116-
| `GITHUB_CLIENT_SECRET` | secret | no | GitHub OAuth app client secret |
117-
| `MISTRAL_API_KEY` | secret | no | Mistral AI API key |
118-
| `SHARED_STORAGE_BUCKET` | var | no | S3 bucket name |
119-
| `SHARED_STORAGE_ENDPOINT` | var | no | S3 endpoint URL |
120-
| `SHARED_STORAGE_ACCESS_KEY_ID` | secret | no | S3 access key |
121-
| `SHARED_STORAGE_SECRET_ACCESS_KEY` | secret | no | S3 secret key |
122-
| `SHARED_STORAGE_PUBLIC_URL` | var | no | S3 public URL |
123-
| `EMAIL_PROVIDER` | var | no | Email provider (e.g. `scaleway`) |
124-
| `EMAIL_FROM` | var | no | Sender email address |
125-
| `SCW_SECRET_KEY` | secret | no | Scaleway secret key |
126-
| `SCW_PROJECT_ID` | var | no | Scaleway project ID |
127-
| `SCW_REGION` | var | no | Scaleway region |
128-
129-
In worker mode, the `DATABASE` binding provides direct database access. `POSTGATE_URL` and `POSTGATE_TOKEN` are only needed in Docker mode (see below).
109+
Bindings (`DATABASE`, `ASSETS`) are set with `ow infra env bind` during the initial setup (see step 5 above). They connect the worker to its database and assets storage at runtime.
110+
111+
In worker mode, the `DATABASE` binding provides direct database access — no Postgate HTTP proxy needed. `POSTGATE_URL` and `POSTGATE_TOKEN` are only required in Docker mode, where there are no runtime bindings.
130112

131113
## Docker mode
132114

@@ -144,14 +126,7 @@ bun start
144126

145127
The server listens on `PORT` (default `7000`).
146128

147-
In Docker mode, there is no `DATABASE` binding. Set these additional variables in `.env`:
148-
149-
| Variable | Required | Description |
150-
| ---------------- | -------- | -------------------------------- |
151-
| `POSTGATE_URL` | yes | Postgate HTTP proxy URL |
152-
| `POSTGATE_TOKEN` | yes | Postgate token (`pg_xxx` format) |
153-
154-
All other environment variables from the table above also apply (without the bindings).
129+
In Docker mode, `POSTGATE_URL` and `POSTGATE_TOKEN` must be set in `.env` to connect to the Postgate HTTP proxy. All other environment variables from the README also apply (without the bindings).
155130

156131
## Managing projects
157132

‎README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,3 +122,52 @@ console.log(users[0], users.count);
122122
- SQL validation and injection prevention
123123
- Token-based access control per database
124124
- Same API works from workers (OpenWorkers runtime)
125+
126+
## Environment Variables
127+
128+
The API runs in two modes with different configuration:
129+
130+
- **Worker mode** — deployed on OpenWorkers, uses `DATABASE` binding for direct DB access
131+
- **Docker/standalone mode** — uses `POSTGATE_URL` + `POSTGATE_TOKEN` for HTTP-based DB access
132+
133+
| Variable | Type | Required | Description |
134+
| ---------------------------------- | ------- | -------- | ---------------------------------------- |
135+
| `DATABASE` | binding | worker | Database binding (direct DB access) |
136+
| `ASSETS` | binding | worker | Assets storage binding (SvelteKit files) |
137+
| `POSTGATE_URL` | var | docker | Postgate HTTP proxy URL |
138+
| `POSTGATE_TOKEN` | secret | docker | Postgate token (`pg_xxx` format) |
139+
| `POSTGATE_SYSTEM_TOKEN_SECRET` | secret | yes | System token HMAC secret (>= 32 chars) |
140+
| `APP_URL` | var | yes | Dashboard URL (for OAuth redirects) |
141+
| `JWT_ACCESS_SECRET` | secret | yes | JWT signing secret (>= 32 chars) |
142+
| `JWT_REFRESH_SECRET` | secret | yes | JWT refresh token secret (>= 32 chars) |
143+
| `GITHUB_CLIENT_ID` | var | no | GitHub OAuth app client ID |
144+
| `GITHUB_CLIENT_SECRET` | secret | no | GitHub OAuth app client secret |
145+
| `MISTRAL_API_KEY` | secret | no | Mistral AI API key (transcription) |
146+
| `SHARED_STORAGE_BUCKET` | var | yes | S3 bucket name |
147+
| `SHARED_STORAGE_ENDPOINT` | var | yes | S3 endpoint URL |
148+
| `SHARED_STORAGE_ACCESS_KEY_ID` | secret | yes | S3 access key |
149+
| `SHARED_STORAGE_SECRET_ACCESS_KEY` | secret | yes | S3 secret key |
150+
| `SHARED_STORAGE_PUBLIC_URL` | var | yes | S3 public URL |
151+
| `EMAIL_PROVIDER` | var | no | Email provider (`scaleway`) |
152+
| `EMAIL_FROM` | var | no | Sender email address |
153+
| `SCW_SECRET_KEY` | secret | no | Scaleway secret key |
154+
| `SCW_PROJECT_ID` | var | no | Scaleway project ID |
155+
| `SCW_REGION` | var | no | Scaleway region |
156+
157+
### System tokens
158+
159+
When the API executes SQL on a user's database (via `/api/v1/databases/:id/exec`), it authenticates to Postgate using a **system token**. These tokens are deterministic — derived from `HMAC-SHA256(POSTGATE_SYSTEM_TOKEN_SECRET, "system_token:{databaseId}")` — so they don't need to be stored in plain text. Only the hash is persisted in the `database_tokens` table.
160+
161+
This means the API can regenerate the token on the fly for any database, as long as `POSTGATE_SYSTEM_TOKEN_SECRET` stays the same. If the secret changes, all system tokens become invalid and must be recreated.
162+
163+
### Shared storage
164+
165+
The `SHARED_STORAGE_*` variables configure the S3-compatible bucket used to store worker assets (uploaded scripts, static files). Without these, workers cannot be deployed. Any S3-compatible provider works (Cloudflare R2, AWS S3, MinIO, etc.).
166+
167+
`SHARED_STORAGE_PUBLIC_URL` is the public-facing URL used to serve assets to clients (e.g. `https://assets.example.com`).
168+
169+
### Email
170+
171+
The `EMAIL_*` and `SCW_*` variables are optional. When configured, the API can send transactional emails (e.g. invitations). Currently only Scaleway TEM is supported as a provider (`EMAIL_PROVIDER=scaleway`).
172+
173+
See [DEPLOY.md](./DEPLOY.md) for deployment instructions.

0 commit comments

Comments
 (0)