# Dwapa Server: deployment guide

NestJS API. Needs **Node.js 22 LTS** (20.12 or newer works) and **MySQL 8.0 or newer** (not MariaDB).
Redis is **not** required.

## 1. Create the database (once)

`database/dwapa-platform-setup.sql` creates the `dwapaDB` database, every table, and the first
super-admin login. Run it with any MySQL user that can create databases:

```bash
mysql -h <host> -P <port> -u <user> -p < database/dwapa-platform-setup.sql
```

(MySQL Workbench: open the file and run it. Command line is the most reliable.)
It is safe to run again; it never drops or duplicates anything.

Only this one database is created by hand. **Each customer's own database is created by the
server automatically** when a super admin adds an organisation in the app. For that, the MySQL
user in `.env` must be allowed to `CREATE DATABASE` (on managed MySQL, use the admin user).

## 2. Configure

A ready `.env` is included. The JWT secrets are already generated; open it and fill in every line
marked `FILL IN` (`.env.example` lists all optional settings too). These are the values that matter:

| Variable | Value |
| --- | --- |
| `NODE_ENV` | `production` |
| `PORT` | port the API listens on (default 4000) |
| `CORS_ORIGINS` | the exact URL(s) of the web app, comma-separated, e.g. `https://pos.example.com` |
| `TRUST_PROXY` | `1` if behind nginx/IIS/a load balancer, otherwise `0` |
| `PLATFORM_DB_HOST` / `_PORT` / `_USER` / `_PASSWORD` | the MySQL server from step 1 |
| `PLATFORM_DB_NAME` | `dwapaDB` (must match the SQL file) |
| `PLATFORM_DB_SSL` | `true` if the MySQL server requires TLS, else `false` |
| `TENANT_DB_HOST` / `_PORT` / `_USER` / `_PASSWORD` / `_SSL` | normally the same MySQL server and user as above |
| `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET` | two different long random strings (see below) |

If you ever need new secrets: `openssl rand -hex 48`.

Cookies: if the web app and the API are on the same site (e.g. `app.example.com` and
`api.example.com`) the defaults are fine. If they are on different domains, set
`COOKIE_SAMESITE=none` and `COOKIE_SECURE=true` (HTTPS required).

Everything else in `.env.example` (Redis, payments, web push, entitlement keys) is optional and
can stay empty.

## 3. Install, build, start

```bash
npm ci                 # installs dependencies (the build needs the dev ones too)
npm run build
npm run migrate        # should print "applied [none]" for dwapaDB; that confirms the database is current
npm run start:prod     # listens on PORT, API under /api
```

Run `npm run start:prod` under a process manager (pm2, systemd, NSSM on Windows) so it restarts
on reboot. After a successful start you should see
`Dwapa server listening on http://localhost:<PORT>/api`.

## 4. First login

The super admin signs in with the email `admin@sleekteq.com` and the password provided
separately. **Leave "Organisation slug" blank.** Change the password after the first login.

## Updating later

Replace the source, then `npm ci && npm run build && npm run migrate` and restart. `npm run migrate`
brings the platform database **and every organisation's database** up to date. The server refuses
to serve a database that is behind, so always run it after an update.

## Troubleshooting

- `Could not provision the organisation database`: the MySQL user lacks `CREATE DATABASE`, or the
  `TENANT_DB_*` settings are wrong.
- `ERROR 1273 / Unknown collation utf8mb4_0900_ai_ci`: the server is MariaDB or MySQL 5.7. Use MySQL 8.0+.
- Browser shows a CORS error: `CORS_ORIGINS` must equal the web app's exact origin (scheme, host, port, no trailing slash).
- Config validation error at start: a required `.env` value above is missing.