# 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://`. 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` | | `Grains__Permits__Notifications__Sms__UserName`, `__Password` | SMS provider account (production only; secret). Notification settings: `Grains:Permits:Notifications` (Enabled, PushUrl, SendSmsToOwnersWithoutApp = legacy SEND_SMS_GN_DIST, Sms:Enabled/Provider). Development: off; QA: push on, SMS off; production: push on, SMS on | Connection string shape (values are examples only): `User Id=;Password=;Data Source=:1521/;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) 5c. `db/role-co.sql` - new role CO with the same rights as GTO: role row (NTP schema) + copy of every GTO row in GRAINS_SCREEN_PERMISSIONS (safe to re-run) 7. `db/grains-jobs.sql` - tables of the scheduled jobs (`GRAINS_JOBS`, `GRAINS_JOB_RUNS`), primary schema. Without it the scheduler stays idle. Jobs are then started, stopped and timed on the SU screen "المهام المجدولة" (`/jobs`); nothing runs until a job is started there. `Jobs:SchedulerEnabled=false` (set in appsettings.Development.json) switches the scheduler loop off for a process 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/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='' 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`.