Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs: point new users at the first API key and the published image

Yudhi Armyndharisc9c8317f9e60
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a3c6cf061..bcceac72e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -21,14 +21,13 @@ See `docs/03-system-architecture.md` for the bigger picture.
OpenWA targets **Node.js 22+**.
```bash
-# backend
-npm install
-npm run start:dev # hot-reload, default port 2785
-
-# dashboard (separate terminal)
-cd dashboard && npm install && npm run dev
+npm ci
+npm run dev # API on 2785, dashboard (Vite) on 2886
```
+Dashboard dependencies install with the root ones (postinstall). `npm run start:dev` runs the API
+alone. Use `npm install` only when intentionally changing dependencies.
+
Default storage is SQLite, so no external services are required to run locally.
No `.env` is needed: the first boot writes `data/.env.generated` with these defaults. Create a
diff --git a/README.md b/README.md
index 8ea62494a..36946a09f 100644
--- a/README.md
+++ b/README.md
@@ -188,6 +188,11 @@ docker compose -f docker-compose.dev.yml up -d
# Swagger: http://localhost:2785/api/docs
```
+**Your API key.** The first boot generates an admin API key, prints it once in the log and stores it at
+`/app/data/.api-key` inside the container. Read it with `docker exec openwa-api cat /app/data/.api-key`,
+then use it to sign in to the dashboard and as the `X-API-Key` header wherever this README shows
+`YOUR_API_KEY`. Later boots log only a masked prefix. See [API Key](docs/README.md#api-key).
+
> **Using Podman instead of Docker?**
> Podman rootless mode requires the socket to be running and `DOCKER_HOST` to be set:
>
@@ -218,6 +223,8 @@ npm run dev
# Swagger: http://localhost:2785/api/docs
```
+The first boot writes the admin API key to `data/.api-key` (read it with `cat data/.api-key`).
+
Use `npm install` instead when intentionally changing dependencies. OpenWA's committed lockfile uses
registry artifacts only, so npm 12 works with its secure default that blocks Git dependencies; do not
disable that policy globally.
@@ -313,6 +320,22 @@ without one, and a production boot rejects default credentials such as `openwa`
> - `linux/amd64`
> - `linux/arm64`
+To run a published image instead of building from source, add a `docker-compose.override.yml` next to
+`docker-compose.yml`:
+
+```yaml
+services:
+ openwa-api:
+ image: ghcr.io/rmyndharis/openwa:latest
+```
+
+Run `docker compose pull openwa-api && docker compose up -d --no-build`, and use the same command to
+upgrade. Pin a release by replacing `latest` with its version number. Once the image is pulled, Compose
+runs it and builds nothing. The service keeps its `build:` section, so if the pull fails (a mistyped tag,
+no registry access) Compose falls back to building from source and tags that build with the published
+name; `--no-build` makes that case fail instead. For the same reason, do not use `--build` or
+`docker compose build` with this override.
+
## πŸ”Œ Ports
| Service | Port | Description |
@@ -325,6 +348,8 @@ without one, and a production boot rejects default credentials such as `openwa`
## πŸ“‘ API Examples
+Replace `YOUR_API_KEY` with your admin key (see [Quick Start](#-quick-start) for where to find it).
+
### Create a Session
```bash
diff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.md
index 5d5e13260..8b59fab2f 100644
--- a/docs/11-operational-runbooks.md
+++ b/docs/11-operational-runbooks.md
@@ -491,8 +491,11 @@ curl -X POST http://localhost:2785/api/sessions/{sessionId}/messages/send-text \
```
> If you deploy the published image instead of building from source β€” your own compose file with
-> `image: ghcr.io/rmyndharis/openwa:<tag>` β€” replace steps 5-6 with editing that tag and running
-> `docker compose pull`.
+> `image: ghcr.io/rmyndharis/openwa:<tag>` β€” replace steps 5-6 with editing that tag, running
+> `docker compose pull openwa-api`, and confirming the image landed with
+> `docker image inspect ghcr.io/rmyndharis/openwa:<tag>`. `docker compose run` in step 7 has no
+> `--no-build`, so when the service keeps a `build:` section a failed pull would otherwise build from
+> source under the published name. Run step 8 as `docker compose up -d --no-build`.
> On Kubernetes with the chart in `charts/openwa`, take the step 2 backup with the Helm lines in
> Runbook: Database Backup and the step 3 export first, then replace steps 4-8 with checking out the
diff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.md
index 751813c7e..ccf1905a1 100644
--- a/docs/14-migration-guide.md
+++ b/docs/14-migration-guide.md
@@ -795,7 +795,7 @@ docker compose down
# The repo's compose file BUILDS the API image from source:
git pull && docker compose up -d --build
# Deployments pinned to a published image instead (ghcr.io/rmyndharis/openwa:<version>)
-# bump the tag in their compose file, then: docker compose pull && docker compose up -d
+# bump the tag in their compose file, then: docker compose pull openwa-api && docker compose up -d --no-build
# 4. Wait for health β€” every route lives under the /api prefix
for i in {1..30}; do
@@ -919,7 +919,8 @@ cp "$BACKUP_DIR/.env" .
cp "$BACKUP_DIR/docker-compose.yml" .
# 5. Start the target version. The repo compose BUILDS the image, so check out the tag and rebuild;
-# a deployment pinned to a published image bumps the tag and runs `docker compose pull` instead.
+# a deployment pinned to a published image bumps the tag and runs
+# `docker compose pull openwa-api && docker compose up -d --no-build` instead.
echo "▢️ Starting v${TARGET_VERSION}..."
git checkout "v${TARGET_VERSION}"
docker compose up -d --build
diff --git a/docs/15-project-roadmap.md b/docs/15-project-roadmap.md
index dfae56239..ee1e3e646 100644
--- a/docs/15-project-roadmap.md
+++ b/docs/15-project-roadmap.md
@@ -771,9 +771,12 @@ Do the registry checks logged **out**. A promotion can look green while the tags
everyone else β€” that is the failure mode that took `latest`, `0.10` and `0.10.5` offline after
v0.10.5 published its GitHub Release.
-Upgrading a Compose deployment is `git pull && docker compose up -d --build`: the bundled
-`docker-compose.yml` **builds** the API service rather than pulling it, so `docker compose pull` is
-a no-op for OpenWA itself.
+Upgrading a Compose deployment that builds from source is `git pull && docker compose up -d --build`:
+the bundled `docker-compose.yml` **builds** the API service rather than pulling it, so
+`docker compose pull` is a no-op for OpenWA itself. A deployment whose `docker-compose.override.yml`
+sets a published image (see the README) upgrades with
+`docker compose pull openwa-api && docker compose up -d --no-build` instead; `--build` there would
+build from source and tag the result with the published image name.
## 15.8 Success Metrics
diff --git a/docs/20-community-guidelines.md b/docs/20-community-guidelines.md
index a938a32fa..a087f5f8f 100644
--- a/docs/20-community-guidelines.md
+++ b/docs/20-community-guidelines.md
@@ -63,8 +63,8 @@ cd openwa
# 3. Add upstream remote
git remote add upstream https://github.com/rmyndharis/OpenWA.git
-# 4. Install dependencies
-npm install
+# 4. Install the locked dependencies (also installs dashboard dependencies)
+npm ci
# 5. Start development (API + dashboard). No .env is needed: the first boot writes
# data/.env.generated. A .env only pins values; if you copy .env.example, set
diff --git a/docs/README.md b/docs/README.md
index e65deada6..d1a869477 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -83,19 +83,20 @@
git clone https://github.com/rmyndharis/OpenWA.git
cd OpenWA
-# Install the locked dependencies & configure
+# Install the locked dependencies (also installs dashboard dependencies)
npm ci
-cp .env.minimal .env
-# Create data directories
-mkdir -p data/sessions data/media
+# Optional: .env.minimal pins database, storage, Redis/queue, session path, engine and Puppeteer
+# settings over Dashboard > Infrastructure, and turns off session auto-start
+# cp .env.minimal .env
-# Run
-npm run start:dev
+# Run the API and the dashboard
+npm run dev
```
Access:
+- Dashboard: `http://localhost:2886`
- API: `http://localhost:2785/api`
- Swagger: `http://localhost:2785/api/docs`
- Health: `http://localhost:2785/api/health`
@@ -115,7 +116,7 @@ Access (the dashboard is bundled into the API and served on the same port):
- Dashboard: `http://localhost:2785`
- API: `http://localhost:2785/api`
-- Swagger: `http://localhost:2785/api/docs`
+- Swagger: `http://localhost:2785/api/docs` (off under this compose file's `NODE_ENV=production` unless `ENABLE_SWAGGER=true`)
### API Key
@@ -124,7 +125,9 @@ OpenWA seeds a default API key on first run and writes it to:
- `data/.api-key` (development)
- `/app/data/.api-key` inside the API container when using Docker
-The startup logs also print the initial key. By default a cryptographically
+With Docker, read it with `docker exec openwa-api cat /app/data/.api-key`.
+
+The startup log prints the full key only on the boot that created it; later boots show a masked prefix. By default a cryptographically
random `owa_k1_...` admin key is generated on first run in all environments; set
`ALLOW_DEV_API_KEY=true` to seed the well-known `dev-admin-key` for local
development only. Use an admin key to create additional keys with
diff --git a/src/common/docs-governance.spec.ts b/src/common/docs-governance.spec.ts
index 5fc6c2356..c96041736 100644
--- a/src/common/docs-governance.spec.ts
+++ b/src/common/docs-governance.spec.ts
@@ -67,4 +67,28 @@ describe('governance docs match the repository', () => {
expect(documented.size).toBeGreaterThanOrEqual(20);
expect(applied.filter(label => !documented.has(label))).toEqual([]);
});
+
+ // The override keeps the service's `build:` section, so `--build` would tag a source build with the
+ // published image name. The README, the release guide and the migration guide give one upgrade command.
+ it('gives the published-image override one upgrade command in the README, docs/14 and docs/15', () => {
+ const command = 'docker compose pull openwa-api && docker compose up -d --no-build';
+ const readme = between(read('README.md'), 'To run a published image', '\n## ');
+ expect(readme).toContain(command);
+ expect(readme).not.toMatch(/still builds from source/);
+ // Compose pulls a missing image first; only a failed pull falls back to a source build.
+ expect(readme).not.toMatch(/missing image would be built/);
+ expect(readme).toMatch(/if the pull fails/);
+ expect(between(read('docs/15-project-roadmap.md'), 'Upgrading a Compose deployment', '\n## ')).toContain(command);
+ const migration = read('docs/14-migration-guide.md');
+ expect(between(migration, '# 3. Move to the new version', '# 4.')).toContain(command);
+ expect(between(migration, '# 5. Start the target version', 'echo')).toContain(command);
+ });
+
+ // `docker compose run` has no --no-build, so the runbook confirms the pull landed before step 7.
+ it('keeps the runbook published-image upgrade from building after a failed pull', () => {
+ const note = between(read('docs/11-operational-runbooks.md'), '> If you deploy the published image', '\n\n');
+ expect(note).toContain('`docker compose pull openwa-api`');
+ expect(note).toContain('`docker image inspect ghcr.io/rmyndharis/openwa:<tag>`');
+ expect(note).toContain('`docker compose up -d --no-build`');
+ });
});