NTP_V2/docs/ENVIRONMENTS.md

127 lines
7.0 KiB
Markdown

# Environments: Development, QA, Production
One code base, three environments. Everything that differs is configuration; **secrets are never committed**.
| | Development | QA | Production |
|---|---|---|---|
| `ASPNETCORE_ENVIRONMENT` | `Development` | `QA` | `Production` |
| API settings file | `appsettings.Development.json` | `appsettings.QA.json` | `appsettings.Production.json` |
| Swagger / OpenAPI | on | off | off |
| Log level | Information (`NTP.Infrastructure` Debug) | Information | Warning (`NTP` Information) |
| `Jwt__Key` | optional (random per start) | **required** | **required** |
| Oracle database | QA database (developer machine) | QA database | production database |
| Web build | `npm run dev` (Vite proxy to `https://localhost:7180`) | `npm run build:qa` | `npm run build:prod` |
| Web env file | `.env.local` (optional) | `web/.env.qa` | `web/.env.production` |
| Local launch profile | `https` (port 7180) | `https-qa` (port 7181) | not for local use |
## How the API is configured
Settings are layered; later wins:
1. `appsettings.json` (shared defaults, no secrets)
2. `appsettings.{Environment}.json` (this table)
3. `appsettings.Local.json` (**git-ignored**, a developer's own values; copy `appsettings.Local.example.json`)
4. environment variables, e.g. `Jwt__Key`, `ConnectionStrings__NtpSchema` (`__` is the section separator)
### What a QA or production server must provide
Set these in the server's environment (IIS application settings, a Windows service environment, or a secret store), **not** in a file in the repository:
| Setting | Meaning |
|---|---|
| `ConnectionStrings__NAFITHTCS` | Oracle connection string of the primary schema |
| `ConnectionStrings__NtpSchema` | Oracle connection string of the NTP schema |
| `Jwt__Key` | JWT signing key, at least 32 random characters. The app refuses to start outside Development without it |
| `Cors__AllowedOrigins__0` | Origin of the web app, e.g. `https://<web-host>`. Replaces the placeholder in the settings file; until it is set no browser origin is allowed |
| `Auth__SuperUsers__0`, `__1` ... | Logins that may hold role `SU`. Empty in production by default; QA lists its own in `appsettings.QA.json` |
Connection string shape (values are examples only):
`User Id=<schema>;Password=<secret>;Data Source=<host>:1521/<service>;Min Pool Size=1;Max Pool Size=50;Connection Timeout=15;Statement Cache Size=50`
If Oracle ever rejects a password (ORA-01017) the API stops trying that account until it is restarted, so a wrong password
cannot lock the database account. Fix the setting, then restart the service. `/health/ready` reports the reason.
Use `/health/live` for load balancer / uptime checks (it does not touch the database); `/health/ready` opens database connections.
## Database objects
Apply these scripts once per database (not run by the application), in this order:
1. `db/grains-screen-permissions.sql` - role to screen/action permissions (`GRAINS_SCREEN_PERMISSIONS`)
2. `db/registry-create-permissions.sql` - add / edit rights of trucks, trailers and drivers (safe to re-run)
3. `db/disabled-features.sql` - features switched OFF for everybody, SU included (safe to re-run)
4. `db/permits-create-permission.sql` - right to register a turn (تسجيل دور) from the permits list, granted to GOO (safe to re-run)
5. `db/menu-reorganisation.sql` - new طلبية التموين screen, GOO reports reduced to two, GOO loses ضبط الميزان (safe to re-run)
5b. `db/gto-reports.sql` - GTO gets the ارسالية عطاء التموين and ملخص التوزيع reports (safe to re-run)
6. `db/gnac-finance-screens.sql` - GNAC gets claims, fines, wages, invoices and the invoice check report (safe to re-run)
**Switching a feature off for everybody:** a row with `ROLECODE = 'DISABLED'` takes that resource out of the system for all users, SU
included: the menu entry and buttons disappear and the API answers 403. It overrides every other row. Delete the row to bring the
feature back. Currently disabled by `db/disabled-features.sql`: `grains.permits.absence` (إيقاف/تفعيل الاستنكاف) and
`grains.permits.activation` (تفعيل الطلبية).
Roles and their rights live in that table (SU always has everything). Changing a row takes effect within about a minute on the
API and on the user's next page reload or sign-in.
## How the web app is configured
Vite reads `web/.env.{mode}`. The files hold only non-secret values, because everything in them ends up in the public JavaScript.
| Variable | Default | Meaning |
|---|---|---|
| `VITE_API_BASE` | `/api/v1` | API address. Same origin by default: the web server proxies `/api` to the API. For a separate API host use `https://<api-host>/api/v1` and add the web origin to `Cors__AllowedOrigins__0` |
| `VITE_MOCK` | `0` | `1` runs the in-browser mock API (development only) |
```bash
cd web
npm ci
npm run build:qa # -> web/dist for QA (mode qa, web/.env.qa)
npm run build:prod # -> web/dist for production (mode production, web/.env.production)
```
## Running a QA build of the API locally
```bash
cd src/NTP.Api
# secrets for the shell session only (PowerShell: $env:Jwt__Key = '...')
export Jwt__Key='<at least 32 random characters>'
dotnet run --launch-profile https-qa # https://localhost:7181
```
## Checklist when a new environment is created
- [ ] database objects applied (see above) and the permission rows reviewed
- [ ] `ConnectionStrings__*`, `Jwt__Key`, `Cors__AllowedOrigins__0` set; super users set if needed
- [ ] `/health/ready` is Healthy
- [ ] web built with the matching mode and published behind the same origin as `/api` (or `VITE_API_BASE` set)
- [ ] sign in as SU and as one limited role and compare the menu with the permission table
## QA server (Docker)
One container holds the API and the built web app (the API serves `wwwroot`), listening on `127.0.0.1:8081` of the QA server. A reverse
proxy publishes it as `https://ntpv2.nafithit.com/` (`deploy/qa/apache-ntpv2.conf` is the Apache virtual host; it is applied by hand).
```bash
cd deploy/qa
cp .env.example .env # fill in the Oracle connection strings and Jwt__Key; never commit .env
docker compose up -d --build
```
Checks: `curl http://127.0.0.1:8081/health/ready` answers `Healthy`; `docker logs ntpv2` shows the log. Redeploy = copy the new source and run the
last command again. The server copy lives in `/opt/ntpv2/src`.
## Production server (Docker)
Same one-container layout as QA, built with the production web settings (`web/.env.production`) and `ASPNETCORE_ENVIRONMENT=Production`
(Swagger off, warning level logs, no SU logins unless `Auth__SuperUsers__0` is set).
```bash
cd deploy/prod
cp .env.example .env # Oracle connection strings of the PRODUCTION database, a new Jwt__Key, the public origin
chmod 600 .env
docker compose up -d --build
```
`deploy/prod/apache-ntp.conf` is the matching Apache virtual host (applied by hand). Run the `db/` scripts listed above on the production
database first. Check with `curl http://127.0.0.1:8081/health/ready` (`Healthy` means Oracle answers) and `docker logs ntpv2-prod`.