Environments and releases

The cahier asks for three environments — development, pre-production / recette client, production (cahier §13.1, OPS-01). The team adds staging for continuous integration. Servers, Dokploy projects, backups and monitoring are described in the architecture and deployment and operations; this page holds the rules the team follows.

The four environmentsCopy Anchor Link

Assumption — hoco.dz and the host names are placeholders until HOCO confirms the domains (decision register). The docs site is deployed on the VPS with restricted access, from dev, so it always shows the latest plan and contract. How each environment is set up in GitHub and Dokploy is in the deployment runbook.

Local services (pnpm db:start): PostgreSQL 17 on 5442, Redis 7 on 6390, MinIO on 9100 (console 9101), Mailpit SMTP on 1125 and UI on 8125.

Rules per environment

• Staging may break, but not for long. A failed deploy or a broken main flow on staging is fixed or reverted within 2 working hours — it blocks Imad's integration and Akram's design QA.
• Pre-production is frozen during HOCO's test sessions. No candidate is deployed while a session runs; candidates go out before 09:00 or after the session, with French notes listing the fixes.
• Production deploy windows: Sunday to Wednesday, 09:00–14:00. Never on Thursday (the weekend follows), never on the eve of a public holiday, never during the first two days of the pilot. Exception: a hotfix for a Blocker, at any time, with HOCO informed.
• Data never flows down unmasked. After go-live, a copy of production for pre-production has phone numbers, names, e-mails and positions of resellers and delegates replaced. Staging never receives production data.
• Every environment is isolated: its own database, Redis, buckets, secrets, cookie prefix and Firebase project.

Deployment flowCopy Anchor Link

• The image recipe is docker/app.Dockerfile with the APP build argument (server, dashboard, web). The worker runs from the server image (ADR-004).
• The server image is built once per commit and promoted: production runs the exact server image that passed pre-production.
• The Next apps are rebuilt per environment from the same commit, because NEXT_PUBLIC_* values are inlined at build time. Nothing else differs between those builds.
• Images are tagged with the commit SHA and the version. CI triggers the staging and pre-production deploys; the production deploy is triggered by Anis, never by a merge.

Order of a deploymentCopy Anchor Link

The server goes first, the mobile apps last.

1. Backup. Production: a fresh dump before every deploy that contains a migration, on top of the nightly backups.
2. Migrations. The new api container runs prisma migrate deploy at start-up, before it accepts traffic; the worker never migrates. Migrations are additive (expand then contract), so the previous version keeps working while they run.
3. api and worker. The new api must answer /ready (database, Redis, migrations) before the old one stops.
4. Smoke test. /health returns the new version; a back-office sign-in; one read per app; one job processed by the worker.
5. Back-office and reseller web.
6. Mobile apps. A store release goes out only when the server version it needs is in production. The server stays compatible with every app version at or above the minimum version.
7. Version policy. If the new app version must be forced, raise the minimum in BO-66.

Mobile release trainsCopy Anchor Link

• A staged rollout is halted as soon as the crash-free rate of the new version drops under 99 % or a Blocker is reported.
• Closed testing means a testers list. Every pilot reseller and delegate must be on the list (by e-mail or through a Google Group) before the invitation link can open the store page. The pilot list is prepared with HOCO before training (LCH-02); unplanned sign-ups during the pilot are added to the group the same day.
• The first submission of each app, the data-safety form and the location declaration are reviewed by Google and can take several days: they are done in MOB-14, well before go-live.
• versionName comes from the tag; versionCode is the CI run number. Both apps share the version line; an app that did not change is not uploaded.

Versions and changelogsCopy Anchor Link

• CHANGELOG.md at the root of each repository, written in the release PR from the squash commits since the previous tag (git log --oneline v0.3.0..HEAD), grouped Added, Changed, Fixed, with task ids.
• Release notes for HOCO, in French, short and per app (back-office, reseller app, delegate app, reseller web). Sent with each candidate and each production release, and summarised on the Progress page.
• Play "What's new": French, at most 500 characters per app.

Release checklistCopy Anchor Link

Before cutting:

• Every task planned for the release is done per the definition of done on staging; what is not ready is behind a flag.
• No Blocker or Critical issue open on the release's GitHub milestone.

Cut and candidate:

• release/x.y.z created from dev; versions bumped; CHANGELOG.md written; release PR into master opened as a draft.
• vX.Y.Z-rc.1 tagged; pre-production deployed; migrations ran; smoke test passed.
• HOCO's testers notified: French notes, what to test, known issues.

Acceptance:

• The release's acceptance scenarios pass on pre-production — for 1.0.0, the priority scenarios of cahier §12 (acceptance scenarios, QA-02).
• Every fix landed on the release branch and was merged back into dev.

Go:

• The last nightly backup succeeded; a restore has been tested at least once (SRV-28).
• No contracted operation of the release answers 501 NOT_IMPLEMENTED.
• Monitoring and alerts green; the Sentry release created.
• HOCO informed of the production window at least 24 hours ahead, with the notes.
• Merge into master, tag, production deploy in the window, smoke test.
• master merged back into dev; milestone closed; GitHub Release published with the notes.
• Mobile: store release after the server; minimum and latest versions updated in BO-66.

RollbackCopy Anchor Link

If the smoke test of a production deploy fails, roll back first, investigate after.

Feature flagsCopy Anchor Link

• Business settings are product features, not flags: order minimums, payment methods, GPS tolerance and the other parameters of ADM-03, edited in BO-64 through admin.settings.update.
• Release flags hide unfinished or V2 features: boolean settings named feature.<name>, delivered to the apps with the public settings of appConfig.get. The back-office hides V2 items until their release flag is on.
• Rules: off by default in production; each flag has an owner and a removal task; a flag is removed at most two releases after it is on everywhere; flags never replace permissions (those are RBAC).
• Assumption — the feature.* naming and its delivery through app-config are confirmed in SRV-07 (settings service).

Maintenance modeCopy Anchor Link

• Switch: BO-66, through admin.appVersions.crud (ADM-07). The API answers 503 MAINTENANCE with details.until; the apps show their system state (RA-36, DA-28); the delegate app keeps working offline and syncs afterwards.
• When: a migration that cannot run online, infrastructure work, a security incident.
• Planned maintenance is announced to HOCO 48 hours ahead, outside field hours (after 20:00, Sunday to Wednesday), never during the pilot's first week and never during Ramadan.
• Forced update: raising the minimum version of an app and platform makes the API answer 426 UPGRADE_REQUIRED with details.storeUrl.