Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs: point new users at the first API key and the published image
Yudhi Armyndharisc9c8317f9e60
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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 adiff --git a/README.md b/README.mdindex 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 usesregistry artifacts only, so npm 12 works with its secure default that blocks Git dependencies; do notdisable 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```bashdiff --git a/docs/11-operational-runbooks.md b/docs/11-operational-runbooks.mdindex 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 thediff --git a/docs/14-migration-guide.md b/docs/14-migration-guide.mdindex 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 prefixfor 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 --builddiff --git a/docs/15-project-roadmap.md b/docs/15-project-roadmap.mdindex 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 tagseveryone else β that is the failure mode that took `latest`, `0.10` and `0.10.5` offline afterv0.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 Metricsdiff --git a/docs/20-community-guidelines.md b/docs/20-community-guidelines.mdindex a938a32fa..a087f5f8f 100644--- a/docs/20-community-guidelines.md+++ b/docs/20-community-guidelines.md@@ -63,8 +63,8 @@ cd openwa# 3. Add upstream remotegit 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, setdiff --git a/docs/README.md b/docs/README.mdindex e65deada6..d1a869477 100644--- a/docs/README.md+++ b/docs/README.md@@ -83,19 +83,20 @@git clone https://github.com/rmyndharis/OpenWA.gitcd 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 cryptographicallyrandom `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 localdevelopment only. Use an admin key to create additional keys withdiff --git a/src/common/docs-governance.spec.ts b/src/common/docs-governance.spec.tsindex 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`');+ });});