NTP_V2/docs/ENVIRONMENTS.md

5.5 KiB

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)
  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)
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

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