Skip to main content

Frontend Applications CI/CD (frontend)

The DEUSS Frontend CI/CD system automates the build, quality assurance, packaging, and GitOps-driven deployment of the two primary frontend applications:

  1. Whitelabel Application (apps/deuss-frontend / Docker image deuss-whitelabel)
  2. Backoffice / Core Application (apps/deuss-backoffice / Docker image deuss-core)

Primary Goals​

  • Automated Monorepo Building & Code Quality: Build Nx targets (i18n-compile, build, build:bo) and run ESLint (lint) and security audits (npm audit).
  • End-to-End Automated Testing: Execute Playwright test suites (smoke matrix, full matrix, and scheduled nightly runs) with Allure report generation.
  • Containerization: Package compiled static assets into lightweight, security-hardened Alpine Nginx Docker images with runtime environment variable substitution.
  • Helm Chart Linting & Validation: Validate Kubernetes manifests via helm lint and helm template.
  • GitOps Deployment via ArgoCD: Automatically propagate built container image tags (short commit SHAs) to the argocd-k8s-dev GitOps repository, triggering automated synchronization in Kubernetes clusters.

Prerequisites & Configuration​

Required GitLab CI/CD Variables​

Variable NameTypeDescription
CI_JOB_TOKENPredefinedAutomatically provided by GitLab to authenticate against the internal GitLab NPM package registry.
ARGO_PROJECT_TOKENMasked / SecretPersonal/Project Access Token with API push permissions to clone and commit image tag updates to the GitOps repository (argocd-k8s-dev.git).
E2E_ENV_FILE_B64FileBase64-encoded payload of the .env.e2e-dev environment configuration file. Required for decoding during the scheduled nightly E2E job.
RUN_NIGHTLY_E2E_DEVVariableSet to "true" in pipeline schedules to activate the nightly E2E dev test suite.
CI_REGISTRY_USER / CI_REGISTRY_PASSWORDPredefinedGitLab Container Registry authentication credentials.
CI_REGISTRY / CI_REGISTRY_IMAGEPredefinedRegistry host URL and base image path.
PUBLIC_BASE_PATHGlobal VarSet to / in .gitlab-ci.yml.
NX_NO_CLOUDGlobal VarSet to true to disable remote Nx Cloud telemetry and caching.

Runner Requirements​

  • Docker Engine & DinD: Support for running Node.js Alpine, Playwright (mcr.microsoft.com/playwright:v1.58.2-noble), and Docker-in-Docker containers.
  • Runner Tags: Dedicated runner tag required for ArgoCD update jobs (argocd:update-static-env and argocd:update-master).

Necessary Developer Permissions​

  • GitLab Project Access: Developer or Maintainer role to push feature branches, open Merge Requests, and manually trigger optional pipeline jobs.
  • CI/CD Administration: Maintainer / Owner role to update CI/CD File variables (E2E_ENV_FILE_B64) and secret tokens (ARGO_PROJECT_TOKEN).

Configuration Files & Components​

FileDescription
.gitlab-ci.ymlMain GitLab CI pipeline configuration defining stages (build, test, release), workflow rules, job templates, matrix definitions, and ArgoCD push tasks.
.docker/DockerfileDocker build instructions for deuss-whitelabel. Configures Alpine Linux with Nginx and tini, sets up a non-root runtime user, copies compiled artifacts from dist/apps/deuss-frontend/.
.docker/Dockerfile.backofficeDocker build instructions for deuss-core, configured similarly with dist/apps/deuss-backoffice/.
.docker/entrypoint.shContainer initialization script for Whitelabel. Generates Nginx location routing dynamically (if HANDLE_ROUTING=true), validates required runtime environment variables, and performs string replacement (sed) on built static JavaScript/HTML files prior to starting Nginx.
.docker/entrypoint.backoffice.shContainer initialization script for Backoffice. Performs runtime configuration injection for Core API, Keycloak, and Indexer endpoints.
helm-chart/Contains Helm chart templates and values.yaml defining default environment variable configurations, ingress rules (whitelabel and core), resource limits, and service definitions.
note

Docker Compose is not used directly in the CI/CD build pipeline; container images are built via Docker-in-Docker in .gitlab-ci.yml and deployed to Kubernetes clusters via Helm and ArgoCD.

Environments & Deployment​

Environment Overview​

EnvironmentDescriptionDomain Pattern
Master / DevelopmentTracks master branch; redeployed on every mergemaster-whitelabel.<dev-domain>, master-core.<dev-domain>
Static Feature / BranchManaged via ArgoCD ApplicationSets; receives updated image tags on every push to registered branchesPer-branch domain
Dynamic MR EnvironmentsTriggered via DEPLOY label on MRsmr-<MR_number>-whitelabel.<dev-domain>

Deployment Mechanism (GitOps via ArgoCD)​

Deployment does not perform direct kubectl or helm commands from CI. Instead, it follows a strict GitOps model:

[GitLab CI Release Stage]
       │
       ├──> Build & Push Docker Images to GitLab Registry
       │    ├── .../deuss-whitelabel:<SHA>
       │    └── .../deuss-core:<SHA>
       │
       └──> Clone argocd-k8s-dev Git Repository
            ├── Update imageTag in values.yaml using yq
            └── Commit & Push back to argocd-k8s-dev
                     │
                     ▼
             [ArgoCD Controller] ──> Syncs & Deploys to K8s Cluster

Approval Mechanisms​

  • Automatic Master Deployments: Pushes merged into master automatically trigger docker:whitelabel, docker:backoffice, and argocd:update-master.
  • Merge Request Guardrails: Pipeline workflow blocks duplicate merge_request_event pipelines to prevent redundant jobs.
  • Manual E2E Testing: e2e:full:matrix and non-master e2e:smoke:matrix require explicit manual trigger by a developer in the GitLab UI.

Pipeline Stages & Jobs​

┌─────────────────────────────────────────────────────────────────────────┐
│                              STAGES                                     │
├──────────────────┬──────────────────────┬───────────────────────────────┤
│  1. build        │  2. test             │  3. release                   │
├──────────────────┼──────────────────────┼───────────────────────────────┤
│ build:whitelabel │ e2e:smoke:matrix     │ docker:whitelabel             │
│ build:backoffice │ e2e:smoke:allure     │ docker:backoffice             │
│ lint             │ e2e:full:matrix      │ argocd:update-static-env      │
│ audit            │ e2e:full:allure      │ argocd:update-master          │
│ lint:helm        │ e2e:dev:nightly      │                               │
│                  │ e2e:dev:nightly:allure│                               │
└──────────────────┴──────────────────────┴───────────────────────────────┘

Stage 1: Build​

  • build:whitelabel: Runs npm run build using Node 22 Alpine, generates static output at dist/apps/deuss-frontend/.
  • build:backoffice: Runs npm run build:bo, generates static output at dist/apps/deuss-backoffice/.
  • lint: Executes npm run lint across monorepo projects once builds pass.
  • audit: Executes npm audit (runs automatically on git tags, manual on branches; allow_failure: true).
  • lint:helm: Validates Helm templates using helm lint helm-chart and helm template helm-chart.

Stage 2: Test​

  • e2e:smoke:matrix: Parallel matrix run across 5 Playwright projects (investor, issuer, trading, navigation, account) targeting @smoke tagged specs. Runs automatically on master, manual on feature branches.
  • e2e:smoke:allure: Aggregates Allure test artifacts into a single merged report.
  • e2e:full:matrix: Parallel matrix run across 13 Playwright test suites (including mobile, tablet, error-states, design-audit). Manual trigger.
  • e2e:full:allure: Merges full E2E test results into Allure reports.
  • e2e:dev:nightly: Nightly scheduled E2E execution against dev environment. Decodes $E2E_ENV_FILE_B64 to .env.e2e-dev. Runs npm run e2e:dev -- --max-failures=20 with a 2-hour timeout and resource_group: e2e-dev-nightly.

Stage 3: Release​

  • docker:whitelabel: Builds Docker image using .docker/Dockerfile, tags with $CI_COMMIT_SHORT_SHA, :latest, and optional tag label, pushes to GitLab Container Registry.
  • docker:backoffice: Builds Docker image using .docker/Dockerfile.backoffice, tags with $CI_COMMIT_SHORT_SHA, :latest, and optional tag label, pushes to registry.
  • argocd:update-master: Runs on master branch push. Clones argocd-k8s-dev, updates .projects.deuss.apps.fe-master.imageTag to $CI_COMMIT_SHORT_SHA with yq, and pushes to GitOps repo with -o ci.skip.
  • argocd:update-static-env: Runs on feature branch push. Checks if branch exists in fe-static-envs elements of argocd-k8s-dev/values.yaml and updates imageTag accordingly.

Pipeline Variants & Triggers​

Pipeline VariantTrigger ConditionKey Actions
Feature BranchGit push to non-master branchRuns build, lint, lint:helm, optional manual E2E tests, builds Docker images, updates feature static env in ArgoCD.
Master BranchGit push / MR merge to masterRuns full build, linting, automatic e2e:smoke:matrix, Docker image packaging, and updates fe-master in argocd-k8s-dev.
Release TagGit tag pushed (e.g. v1.0.0)Runs builds, automated npm audit, builds Docker images tagged with release tag label, pushes to registry.
Nightly ScheduledGitLab Schedule (RUN_NIGHTLY_E2E_DEV=true)Bypasses standard build jobs via .nightly_skip_rule, decodes E2E_ENV_FILE_B64, runs e2e:dev:nightly, generates Allure reports.

How to Use the System​

Standard Developer Tasks​

Developing and Pushing Code​

git checkout -b feature/my-new-feature
git commit -m "feat: add feature"
git push origin feature/my-new-feature

Open GitLab CI/CD → Pipelines to verify that build:whitelabel, build:backoffice, lint, and lint:helm pass cleanly.

Running E2E Tests on a Pipeline​

  1. Navigate to your pipeline in GitLab.
  2. In the test stage, click the Play button on e2e:smoke:matrix or e2e:full:matrix.
  3. Once completed, download or view test reports in job artifacts under apps/deuss-e2e/playwright-report/ or apps/deuss-e2e/allure-report/.

Administrative & Release Tasks​

Creating a Production / Versioned Release​

git tag v0.3.0
git push origin v0.3.0

The pipeline will automatically run audit and push Docker images tagged with v0.3.0 to the container registry.

Deploying to Master Environment​

  1. Merge your approved Merge Request into master.
  2. The argocd:update-master job will run automatically, update values.yaml in argocd-k8s-dev, and push the commit.
  3. ArgoCD will automatically detect the commit and sync the deployment to the Kubernetes cluster.

Setting Up Scheduled Nightly Pipelines​

  1. Navigate to GitLab UI → Build → Pipeline schedules.
  2. Click New schedule and set Target Branch to master.
  3. Add variable RUN_NIGHTLY_E2E_DEV with value true.
  4. Ensure E2E_ENV_FILE_B64 is configured in Settings → CI/CD → Variables as a FILE-type variable: 
    base64 -w 0 apps/deuss-e2e/.env.e2e-dev

Troubleshooting & Rollbacks​

Common Pipeline Failures & Resolutions​

IssueCauseFix
[e2e:dev:nightly] ERROR: Missing E2E env inputE2E_ENV_FILE_B64 variable missing, not defined as a File-type variable, or contains invalid base64.Ensure E2E_ENV_FILE_B64 is set as a File variable type with a valid base64 payload created via base64 -w 0 apps/deuss-e2e/.env.e2e-dev.
NPM Package Authentication Failure (401 Unauthorized)Invalid or expired token in .npmrc via CI_JOB_TOKEN.Verify $CI_JOB_TOKEN permissions under Project Settings → CI/CD → Job Token permissions.
ArgoCD Update Job FailsARGO_PROJECT_TOKEN is invalid, expired, or lacks write access to argocd-k8s-dev.git.Generate a new Project Access Token in argocd-k8s-dev with write repository scope and update ARGO_PROJECT_TOKEN in CI/CD settings.
Container Pod Crashes on Startupentrypoint.sh validation check failed because a required env variable (e.g. OFFCHAIN_URL, RPC_URL, KEYCLOAK_URL) was not set in helm-chart/values.yaml.Update helm-chart/values.yaml to supply all non-empty required environment variable values.

Rollback Procedure​

Option A: Rollback via GitOps Repository​

  1. Identify the short SHA of the last known stable commit (e.g., a1b2c3d).
  2. Edit values.yaml in argocd-k8s-dev to revert the image tag: 
    projects:
      deuss:
        apps:
          fe-master:
            imageTag: "a1b2c3d"
  3. Commit and push. ArgoCD will detect the update and instantly redeploy the previous Docker container image.

Option B: Rollback via GitLab Pipeline Re-run​

  1. Open GitLab CI/CD → Pipelines.
  2. Locate the previous successful pipeline run on the master branch.
  3. Click into the pipeline details and manually re-run the argocd:update-master job. This will re-commit the stable SHA to argocd-k8s-dev.