Deployments¶
Last audited: 2026-07-21.
This guide summarizes how MamNajem changes move through shared environments.
Branch Policy¶
Long-lived backend and architecture branches:
integrationproduction
Backend and architecture changes should be pushed to integration. Production changes are manual and user-controlled.
The customer web repository also uses integration and production as its
long-lived environment branches. Production promotion remains fast-forward-only
and user-controlled.
Keep history linear:
- Fetch and prune before syncing branches.
- Use
git pull --ff-only. - Use fast-forward-only promotion.
- Do not create merge commits.
- Do not push directly to
production.
Before any production rollout, verify production has no commits absent from integration. Use the release worktree checklist for the exact per-repository commands and stop conditions.
Integration Host¶
Since 2026-11-08 integration no longer runs on AWS. The Lightsail backend host and the Amplify integration apps are retired; integration runs on the integration laptop behind a Cloudflare tunnel. Production is unchanged.
| Surface | Integration URL |
|---|---|
API (/v1, webhooks, actuator) |
https://api.mamnajem.win |
Customer web (landing-frontend) |
https://www.mamnajem.win |
Admin (web-admin) |
https://admin.mamnajem.win |
| Docs | https://docs.mamnajem.win |
Web app (web-frontend) |
https://app.mamnajem.win |
| Cognito hosted UI | https://auth-integration.mamnajem.pl (unchanged, AWS) |
GitLab cannot reach the laptop, so nothing pushes to it. A deployer on the
laptop polls GitLab for each repository's newest successful build job on
integration, downloads that job's artifacts and deploys them: the backend JAR
with APP_VERSION set to the commit, static sites by atomic directory swap.
Integration pipelines keep their build jobs and artifacts; instead of deploying,
a bounded verification job (about 20 minutes) waits until the integration URL
serves the pushed commit: the backend's deployed version, or a static site's
build marker.
Backend¶
The backend uses GitLab CI/CD.
Common pipeline areas:
- Maven verify.
- Dependency check.
- Gitleaks.
- Semgrep.
- OpenAPI compatibility checks.
- Scheduled E2E suites.
- Integration live-version verification.
- Production deploy verification.
Integration deploy shape:
- GitLab builds the backend JAR as a job artifact.
- The integration laptop deployer downloads the newest successful build
artifact on
integrationinto/opt/mamnajem-integration/releases/<sha>/. - The
currentsymlink is updated andAPP_VERSIONis set to the commit. - The backend container is recreated and must become ready on
/actuator/health/readiness; otherwise the deployer rolls back. - The integration pipeline waits, bounded, until
https://api.mamnajem.winreports the pushed version.
Production deploy shape:
- Backend image/JAR changes pass CI.
- ECS service deployment is triggered.
- ALB target health and
/actuator/healthverify runtime readiness. - New Relic conditions watch for health, 5xx, CPU, and target issues; CloudWatch logs corroborate failures.
Mobile Frontend¶
The mobile app uses GitLab dispatcher pipelines on integration and production.
Common checks:
- Lint.
- TypeScript.
- Prettier.
- Jest.
- CI helper tests.
- Build configuration assertions.
- New Relic release/dist assertions.
- Firebase config assertions.
Android release flow:
- Build Android release artifact.
- Upload to Google Play internal.
- Promote to closed alpha through GitLab OIDC and Google Workload Identity Federation.
- For integration, publish the Android required-app-update Remote Config after alpha upload.
- For production, the production-track upload is a manual job that promotes from alpha.
iOS release flow:
- Generate native iOS project.
- Install pods.
- Build archive.
- Upload IPA to TestFlight.
- The iOS child pipeline runs for
integrationandproductionparent pipelines.
The mobile repository does not contain the customer Amplify hosting build. A mobile push cannot trigger or publish the customer website.
Customer Web¶
The landing-frontend repository owns the marketing, legal, support, public intake,
native bridge, and mobile association-file surface. The production customer
website is hosted by the retained production AWS Amplify application; the
integration site is served by the integration laptop at
https://www.mamnajem.win. It does not provide Cognito sign-in or the
authenticated product.
Integration deployment:
- Push a completed change to
landing-frontendintegration. - GitLab runs validation, browser smoke checks and the static build.
- The integration laptop pulls the newest successful build artifact.
- The pipeline waits, bounded, until
https://www.mamnajem.winserves the pushed commit's build marker.
The production customer Amplify branch has enableAutoBuild=false; GitLab is
the deployment trigger. There is no scheduled customer-web rebuild.
Production does not auto-build. Promote the already verified integration commit
to production using the fast-forward-only policy, then run the user-controlled
manual production deployment job. Never publish production from a mobile push.
After a customer-web deployment, verify:
/.well-known/assetlinks.json,/.well-known/apple-app-site-association, and/apple-app-site-associationare valid and served with the expected content types.- Native bridge routes preserve their query strings and fragments for
/openand/account/payment, plus supported property, lease, invitation and bank-transfer payment destinations. Stripe checkout, Connect and hosted subscription/rent-payment return targets are unavailable; association paths include only password recovery and invitation acceptance. - Marketing, legal, support, and public intake pages load without exposing an authenticated customer product.
The backend verifies Turnstile tokens submitted by public forms. The integration Turnstile secret is supplied by protected GitLab CI/CD variables during deploy; the production secret is sourced from AWS Secrets Manager.
Web App¶
The web-frontend repository is the React/Vite customer web app. It has an
integration deployment only, at https://app.mamnajem.win (OAuth origin
https://app.mamnajem.win, API https://api.mamnajem.win/v1); it is not part of
the client contract and has no production deployment.
web:build:integration builds the static SPA for integration, writes the build
marker dist/.mamnajem-build.json and keeps dist/ as a one-week artifact. The
integration laptop serves the newest successful artifact with an index.html
fallback for client routes. web:verify:integration waits up to 20 minutes for
https://app.mamnajem.win/.mamnajem-build.json to report the pushed commit.
Documentation Site¶
The docs repository builds a static MkDocs site, but it is not published by
GitLab Pages and no Amplify app is connected to the repository. Integration docs
are served by the integration laptop at https://docs.mamnajem.win. Terraform
owns the production manual-deployment Amplify application, branch, headers,
cache policy, and custom-domain activation for https://docs.mamnajem.pl.
The normal docs:build job performs one strict MkDocs build, creates the
canonical build marker public/.mamnajem-build.json and deterministic ZIP, and
runs verify-docs-deployment-artifact.py. The verifier checks both SHA-256
sidecars, exact ZIP membership and bytes, normalized metadata, and every local
HTML link before the residual scanner runs over public/. The job publishes
public/ and the verified ZIP only as private pipeline artifacts and does not
start an Amplify deployment.
On integration pushes, the integration laptop pulls the newest successful
docs:build artifact and serves public/. verify_integration_docs uses no
credentials: scripts/wait-for-docs-build-marker.py polls
https://docs.mamnajem.win/.mamnajem-build.json for up to 20 minutes, without
following redirects, until its repository is mamnajem/docs and its
candidateSha is the pushed commit.
The only docs deploy job is deploy_production_docs. It is manual and uses
GitLab OIDC with the AWS STS audience. Its rules accept only the protected
production branch and a fresh request whose SHA equals CI_COMMIT_SHA;
durable activation variables are never used in job rules.
Create the requested pipeline with activation_requested="true" and
activation_request_sha="<full candidate SHA>" in the GitLab pipeline inputs
(inputs in POST /projects/:id/pipeline). The request flag accepts only the
strings false and true; the SHA accepts only an empty default or 40 lowercase
hexadecimal characters. Ordinary push pipelines default to no deployment.
Inputs avoid pipeline-variable override restrictions and do not grant deployment
authority: protected activation, sealed-contract and exact-artifact checks below
still apply. Do not lower the project's pipeline-variable permission policy.
The production job no longer has a reset-controller preflight: the controller
lived on the retired Lightsail integration host, and the owner chose on
12 November 2026 to drop the check rather than re-home it. After an activation
run, set MAMNAJEM_ACTIVATION_REQUESTED back to false and clear
MAMNAJEM_ACTIVATION_REQUEST_SHA by hand. The job's after-script still calls
scripts/reset-docs-activation.sh, which reports that no controller answers;
an after-script failure does not fail the deployment.
Before credentials are requested, the manual job requires all of the following:
- The protected
productionenvironment hasMAMNAJEM_ACTIVATION_ENABLED=true. MAMNAJEM_ACTIVATION_SHA,MAMNAJEM_ACTIVATION_REQUEST_SHA, and the only release-matrix variable,MAMNAJEM_SEALED_RELEASE_MATRIX_SHA, all equal the checked-outCI_COMMIT_SHA.- It resolves only
MAMNAJEM_PRODUCTION_ARCHITECTURE_CONTRACT_FILEwithMAMNAJEM_PRODUCTION_ARCHITECTURE_CONTRACT_SHA256. - The protected F9 architecture-contract file exists, its SHA-256 matches, and its production docs entry provides the matching app ID, literal branch, deployment role ARN, and candidate SHA.
The source contains no provider IDs, role ARNs, repository connection, webhook,
deploy token, or static AWS key. A missing, stale, cross-environment, or
placeholder F9 contract fails before OIDC. Once F9 supplies the values, the
job may use only Amplify CreateDeployment, StartDeployment, GetJob, and StopJob
for the manual ZIP deployment. The AWS token is materialized in a mode-0600
temporary file, ambient credential sources are disabled, and the exact assumed
role ARN is checked before deployment. Upload and job polling are bounded;
unknown or timed-out states stop the Amplify job. A successful provider job is
not accepted until the live environment serves the matching build marker. The
independent after_script controller resets the matching activation flag and
then clears its activation SHA for success, failure, or cancellation.
Do not create a docs deployment or bind a custom domain from this repository. Task 11 is the first coordinated activation; it must verify the deployed build marker, ZIP checksum, routes, assets, browser console, and Terraform-owned header set.
Admin Web¶
The admin web app is a Vite + React app using AWS Amplify libraries with the Cognito admin pool. Production admin hosting stays on its Amplify application.
Integration hosting:
- Host: the integration laptop
- Domain:
https://admin.mamnajem.win - Repository:
https://gitlab.com/mamnajem/web-admin
The web-admin GitLab pipeline validates tests, audit, and build output. The integration laptop pulls the newest successful integration build artifact, and the pipeline waits until the admin site serves the pushed commit's build marker. After a web-admin push, check the GitLab pipeline for that commit, then smoke the deployed admin shell. Without an admin session, the minimum smoke is:
- Open
https://admin.mamnajem.win/#founding-pilot. - Confirm the admin sign-in shell loads.
- Confirm the protected admin API returns
401when unauthenticated. - Confirm the loaded
/assets/index-*.jsbundle contains the released UI strings or controls.
Check:
VITE_COGNITO_ADMIN_USER_POOL_IDVITE_COGNITO_ADMIN_CLIENT_ID- Admin user pool membership and groups.
- Backend admin authorization.
Architecture¶
Terraform is the normal mutation path for shared infrastructure.
Areas:
terraform/aws-integrationterraform/aws-productionterraform/googleterraform/gitlab- shared Terraform modules
Expected safe checks:
terraform fmt -recursive -check
./scripts/tf.sh all-validate
Do not run terraform apply unless the change is explicitly approved for the target environment.
Website association inputs¶
Integration and production static builds require MAMNAJEM_STAGING_CLIENT_CONTRACT_FILE (contract JSON), MAMNAJEM_STAGING_CLIENT_CONTRACT_SHA256 (lowercase file SHA-256), and ANDROID_CERT_SHA256_FINGERPRINTS_JSON (canonical uppercase Play signing fingerprints).
While an environment's signing contract is unavailable, MAMNAJEM_ASSOCIATIONS_PENDING=true permits its public/legal pages to build without assetlinks.json or apple-app-site-association. The verifier rejects these files if present in pending mode. Pending mode is allowed only for integration/production; a supplied contract must match the build's NEXT_PUBLIC_APP_ENV.
Remove the pending variable and redeploy per environment once its contract and signing fingerprints exist. App-link association verification is required then; deep links remain unavailable while pending. Do not borrow another environment's contract.
Push verification¶
After pushing changes:
- Watch the GitLab pipeline to a terminal state.
- If it fails, identify the failing job.
- Classify the failure:
- Application.
- Test.
- Contract.
- Security.
- Deploy.
- Infrastructure.
- Report the result and the next required action.