NTP_V2/docs/ENVIRONMENTS.md

7.9 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
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=<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) 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)
  6. 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
  7. 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

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

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

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.