7.0 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:
appsettings.json(shared defaults, no secrets)appsettings.{Environment}.json(this table)appsettings.Local.json(git-ignored, a developer's own values; copyappsettings.Local.example.json)- 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:
db/grains-screen-permissions.sql- role to screen/action permissions (GRAINS_SCREEN_PERMISSIONS)db/registry-create-permissions.sql- add / edit rights of trucks, trailers and drivers (safe to re-run)db/disabled-features.sql- features switched OFF for everybody, SU included (safe to re-run)db/permits-create-permission.sql- right to register a turn (تسجيل دور) from the permits list, granted to GOO (safe to re-run)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)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__0set; super users set if needed/health/readyis Healthy- web built with the matching mode and published behind the same origin as
/api(orVITE_API_BASEset) - 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.