# Production Installation — Secured Release

This guide is for a clean installation of the secured source package. Keep the original source and the previous working installation as rollback copies until the first production smoke test succeeds.

## 1. Requirements

- Ubuntu 22.04/24.04 LTS or another supported Linux server.
- Node.js **22.12+**.
- Go version required by `go.mod` (currently **1.25.8**).
- MySQL 8.x / compatible MySQL server.
- A domain/reverse proxy with HTTPS for production.
- The purchased license key from the member area.

## 2. Install dependencies

From the project root:

```bash
npm run setup
npm run setup:env
```

`setup:env` generates a random JWT secret and a strong initial super-admin password when `.env` does not already exist. It does not overwrite an existing `.env`.

## 3. Configure `.env`

At minimum configure:

```dotenv
APP_ENV=production
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=wa_assistant
DB_PASS=CHANGE_THIS
DB_NAME=db_wa_blast
JWT_SECRET=GENERATED_BY_SETUP_ENV
SUPERADMIN_USERNAME=superadmin
SUPERADMIN_PASSWORD=GENERATED_BY_SETUP_ENV
LICENSE_KEY=YOUR_PURCHASED_LICENSE_KEY
CORS_ALLOWED_ORIGINS=https://your-domain.example
API_ALLOW_QUERY_TOKEN=false
```

Recommended:

```dotenv
SECRET_ENCRYPTION_KEY=ANOTHER_RANDOM_SECRET
API_RATE_PER_MIN=60
API_RATE_BURST=20
```

Do not put API keys, customer data, WhatsApp session files, or `.env` into Git.

## 4. Preflight

Run:

```bash
npm run preflight:production
```

Do not start production if this fails.

## 5. Build frontend

```bash
npm --prefix frontend ci
npm --prefix frontend run build
```

The backend serves `frontend/dist` automatically when `STATIC_DIR` is left at its default.

## 6. Backend tests

Use the exact Go version required by `go.mod`:

```bash
go test ./backend/...
go vet ./backend/...
```

For a complete security dependency check, install the official `govulncheck` tool matching your Go toolchain and run:

```bash
govulncheck ./...
```

## 7. Health check

After the backend starts, a reverse proxy or monitoring system can check:

```text
GET /api/healthz
```

It returns `200` with `{"status":"ok"}` when the process and database are reachable, and `503` otherwise. It does not expose tenant or customer data.

## 8. First start

```bash
go run ./backend
```

Verify:

1. Dashboard opens over HTTPS.
2. Admin login works.
3. Database tables are created/migrated.
4. WhatsApp number can connect.
5. API key can be rotated and used through `Authorization: Bearer ...`.
6. Webhook test reaches the configured endpoint.
7. AI provider can answer a test conversation if configured.
8. Broadcast test is performed against a small, authorized test list.

## 9. systemd

After the first manual smoke test, create a dedicated service user and run the backend from the project directory. Do not run the application as root.

Example service:

```ini
[Unit]
Description=WhatsApp Gateway
After=network-online.target mysql.service
Wants=network-online.target

[Service]
Type=simple
User=wa-assistant
Group=wa-assistant
WorkingDirectory=/opt/whatsapp-gateway
EnvironmentFile=/opt/whatsapp-gateway/.env
ExecStart=/usr/local/go/bin/go run ./backend
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=full
ProtectHome=true
ReadWritePaths=/opt/whatsapp-gateway/data /opt/whatsapp-gateway/.tmp

[Install]
WantedBy=multi-user.target
```

For a permanent deployment, prefer a built backend binary rather than `go run` once the exact build has passed.

## 10. Rollback

Never delete the previous installation before the new version has passed its smoke test. Keep:

- previous application directory
- database backup
- `.env` backup with restricted permissions
- WhatsApp/session data backup according to your operational policy

If migration or startup fails, stop the new service and restore the previous application/data state before retrying.