Before You Begin

Each code block includes a copy button.

The content displayed in the documentation is intended to help you understand what is being created or configured. The copy button copies a platform-specific command that performs the complete operation automatically.

Recommended system requirements

• 16 GB RAM
• Recent multi-core CPU

Pre-requisites

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y docker.io docker-compose-plugin
docker --version

Mac

• We support the current macOS release
• Apple Silicon Mac recommended

• Install Docker Desktop

• Docker Compose is included with Docker Desktop

Windows

• Windows 11 Pro, Enterprise, or Education (Home also works with WSL2, but Pro is smoother for virtualization tooling)
• Virtualization enabled in BIOS (Intel VT-x or AMD-V)
• Install WSL2

wsl --install -d Ubuntu

• Install Docker Desktop

• Use WSL 2 instead of Hyper-V ( Docker Documentation )

Deploy your first project locally in under 5 minutes

After completing the onboarding process, a test project named GitLab Cortex Demo will be automatically created.

What You’ll Deploy

The GitLab Cortex Demo project is a self-contained distributed system designed to showcase how Cortex models, generates, and deploys complete development environments.

In less than 5 minutes, you’ll deploy a fully functional platform including:

• GitLab for source code management
• PostgreSQL as the application database
• OpenLDAP for identity management
• pgAdmin for database administration
• phpLDAPadmin for LDAP administration
• Reverse proxying and TLS termination
• Production-aligned networking and service discovery with Traefik

Why This Project Exists

This project demonstrates how Cortex can:

• Model an entire distributed system from a single source of truth
• Generate deployment artifacts automatically
• Standardize development environments across teams
• Reduce configuration drift between development and production
• Enable developers to run complex systems locally

Important

This environment is intended for demonstration, testing, and evaluation purposes only.

It is not production-ready and should not be deployed as-is. Security, scalability, monitoring, backup, and operational requirements have been intentionally simplified to keep the setup easy to understand and deploy.

Let's get started

Please select the GitLab Cortex Demo project and generate the artifact Docker Compose Files.

Unzip the archive, open a terminal and navigate to the unzipped folder.

Create shared docker networks

docker network create gateway-net
docker network create backend-net

docker network create gateway-net
docker network create backend-net

Generate a root certificate (skip if you already have one)

chmod +x generate-root-ca.bash
./generate-root-ca.bash cortexRootCertificate

bash ./generate-root-ca.bash cortexRootCertificate

If you want your browser and tools (curl, Chrome, etc.) to trust the TLS certificates generated for the platform, you should install the generated root certificate into your system trust store.

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain cortexRootCertificate.crt

sudo cp cortexRootCertificate.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

Import-Certificate -FilePath cortexRootCertificate.crt -CertStoreLocation Cert:\LocalMachine\Root
Get-ChildItem Cert:\LocalMachine\Root

Generate TLS certificates

We'll now generate the application certificates using the provided root certificate.

chmod +x make-certs-development.bash
./make-certs-development.bash ./cortexRootCertificate.crt ./cortexRootCertificate.key

bash ./make-certs-development.bash ./cortexRootCertificate.crt ./cortexRootCertificate.key

We are using here the cortexRootCertificate.* files generated in the previous step. You may replace these files with your own root certificate if you want the generated TLS certificates to be trusted by your internal PKI.

Configure OpenLDAP users

The OpenLDAP container automatically imports LDIF files located in the ldap-custom directory during initialization.

Create a directory named ldap-custom and add a file named 50-users.ldif containing the following user definition.

You may add additional LDAP users by extending this file.

dn: uid=gitlabuser,dc=example,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
cn: Gitlab User
sn: User
uid: gitlabuser
mail: gitlabuser@example.org
uidNumber: 1000
gidNumber: 1000
homeDirectory: /home/gitlabuser
loginShell: /bin/bash
userPassword: password123

dn: uid=gitlabuser,dc=example,dc=org
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
cn: Gitlab User
sn: User
uid: gitlabuser
mail: gitlabuser@example.org
uidNumber: 1000
gidNumber: 1000
homeDirectory: /home/gitlabuser
loginShell: /bin/bash
userPassword: password123

Start the project

The ROOT_CA_FILE argument allows the Chromium container to trust the root certificate used to generate the TLS certificates.

ROOT_CA_FILE=cortexRootCertificate.crt docker compose -f docker-compose-development.yaml -f docker-compose-common.yml up -d --build

$env:ROOT_CA_FILE="cortexRootCertificate.crt"; docker compose -f docker-compose-development.yaml -f docker-compose-common.yml up -d --build

Connect to GitLab

• GitLab
  https://gitlab.dev.cortexdemo.com
• PgAdmin
  https://pgadmin.dev.cortexdemo.com
• PhpLDAPadmin
  https://phpldapadmin.dev.cortexdemo.com

You can connect with the user: gitlabuser@example.org | password123

If you want to connect from your web browser, you'll have to install the root certificate on your local TrustStore and declare the hosts in /etc/hosts

127.0.0.1       gitlab.dev.cortexdemo.com
127.0.0.1       phpldapadmin.dev.cortexdemo.com
127.0.0.1       pgadmin.dev.cortexdemo.com

127.0.0.1       gitlab.dev.cortexdemo.com
127.0.0.1       phpldapadmin.dev.cortexdemo.com
127.0.0.1       pgadmin.dev.cortexdemo.com

Stop the project

docker compose -f docker-compose-development.yaml -f docker-compose-common.yml down

Cortex V1.0 is an operational intelligence platform designed to structure how teams build, organize, deploy, and evolve systems. Below is the complete feature set for version 1.0.

Index

• Organization & Team Management
• Project Management
• Environment Management
• Service Definition & Configuration
• System Visualization
• Artifact Generation
• Feedback & Issue Tracking
• Intel Information

Organization & Team Management

Organization Registration & Onboarding

• Create and initialize an organization workspace
• Guided onboarding flow for initial setup
• Centralized configuration at the organization level
  

Team Member Management

• Invite users to join an organization
• Role-based access and collaboration
• Centralized user management across all projects

Project Management

Project Creation

• Create and manage multiple projects within an organization
• Logical separation of systems, domains, or products

Project-Level Collaboration

• Invite team members to specific projects
• Assign roles and responsibilities per project
• Enable focused collaboration within project boundaries

Environment Management

Target Environments

• Define multiple deployment environments (e.g., dev, stage, preprod, prod)
• Configure ordered deployment pipelines
• Manage environment-specific configurations
  

Key capabilities:

• Environment hierarchy and promotion flow
• Deployment sequencing control
• Environment isolation

Service Definition & Configuration

Service Creation

• Define services as core building blocks of the system
  

Service Configuration

Each service supports:

• Metadata definition
• Custom properties
• Environment variables
• Service dependencies
  

Dependency Management

• Map relationships between services
• Define inter-service communication and order

System Visualization

ServiceMap View

• Visual representation of all services and their dependencies
• Real-time system topology overview
• Improved understanding of system architecture

Artifact Generation

Cortex V1.0 automatically generates operational, deployment, and architectural artifacts from service definitions, environments, and dependencies — ensuring consistency across the entire system lifecycle.

Prometheus Configuration

Cortex generates an organization-wide Prometheus configuration to standardize monitoring across all services and environments.

Key capabilities:

Pre-configured service discovery

Unified metrics collection across environments

Consistent monitoring setup aligned with service definitions

Grafana Configuration

Cortex provides ready-to-use Grafana configurations for visualizing system metrics.

Key capabilities:

Pre-built dashboards aligned with generated Prometheus metrics

Organization-level observability views

Consistent visualization across environments

Jenkins CD Pipeline with BDD Tests

Cortex generates continuous delivery pipelines with integrated behavior-driven testing.

Key capabilities:

Automated pipeline generation per service

Integrated BDD testing stages

Environment-aware deployment steps

Standardized CI/CD structure across projects

System Architecture Document

Cortex automatically produces documentation that reflects the current system design.

Key capabilities:

Up-to-date representation of services and dependencies

Environment-aware architecture views

Consistent and shareable system documentation

Docker Compose Files

Cortex generates Docker Compose configurations to support local development and service orchestration.

Key capabilities:

Service-based container definitions

Dependency-aware startup configuration

Local environment parity with defined services

Helm Charts

Cortex V1.0 generates production-ready Helm Charts to standardize and automate deployments across environments and infrastructure providers.

Key capabilities:

Automated chart generation from service definitions

Environment-aware configuration (dev, stage, preprod, prod)

Dependency-aware deployment ordering

Consistent packaging across cloud and local Kubernetes clusters

Supported Target Platforms

Cortex supports deployment to multiple Kubernetes distributions, enabling portability across cloud and local environments:

AWS EKS (aws-eks)

Azure AKS (azure-aks)

Google GKE (google-gke)

DigitalOcean DOKS (digital-ocean-doks)

Docker Desktop (K8s) (docker-desktop-k8s)

Kubernetes in Docker (KIND) (kind)

Minikube (minikube)

OpenShift (On-Prem) (on-prem-openshift)

Outcome:

Cortex ensures that every system definition directly translates into consistent, production-ready artifacts — reducing manual work and aligning architecture, deployment, and operations.

Feedback & Issue Tracking

Bug Reporting

Report issues directly within the platform

Associate bugs with services or projects

Feedback System

Provide product and system feedback

Continuous improvement loop for teams

Intelligence Layer

Intel Information

Technical Intelligence Hub

• Centralized access to Cortex-related technical and product information
• Searchable knowledge space for platform content, guidance, and updates
• Structured content categories such as:
• Perspectives
• Reference
• Roadmap
• Updates

Supported Content

• Product documentation and usage guidance
• Release information and product evolution
• Architecture and engineering perspectives
• Team knowledge-sharing and platform references

Outcome:
Teams can access a single source of truth for product knowledge, reference material, and Cortex updates.

Summary

Cortex V1.0 provides a unified platform to:

• Structure organizations and teams
• Define and manage projects
• Model services and environments
• Visualize system architecture
• Generate deployment and monitoring artifacts
• Capture feedback and operational intelligence
  

It brings together system design, deployment, and intelligence into a single cohesive layer.

The monolith was not elegant. It was big. Sometimes slow. Occasionally frustrating. But it had one enormous quality: it was understandable.

Everything lived in one place. One repository. One deployment artifact. One runtime. When something broke, you could follow the execution path from controller to database without crossing a network boundary or switching contexts between five teams.

It was not perfect. But it was coherent.

As the company grew, that coherence became a constraint. Builds took longer. Merge conflicts became routine. Teams blocked each other’s releases. Scaling one hotspot required scaling everything. Deployments turned into coordinated events rather than routine operations. The pain was real — and it was structural. So we did what many growing companies do. We broke the monolith.

The Promise of Microservices

The move to microservices was not ideological. It was practical. We wanted smaller cognitive domains. We wanted independent deployments. We wanted teams to own their services end-to-end. We wanted architecture that scaled with the organization.

At first, it worked beautifully. The first few services felt liberating. Smaller repositories. Faster pipelines. Clearer ownership. Teams could ship without waiting on others. Deployments felt lighter. It felt like progress.

Then the number of services doubled. And doubled again.That’s when something subtle started to shift.

When Independence Quietly Disappears

Microservices rarely fail in dramatic ways. They drift. A service needs additional data, so it calls another service synchronously. Later, that second service needs something back. An event subscription is added for convenience. A deployment script introduces an ordering assumption.

Each decision is reasonable in isolation. But architecture is not the sum of isolated decisions. It is the shape of their connections.

Over time, the dependency graph thickens. Services that once felt independent now depend — directly or indirectly — on several others. You still have separate repositories. You still have separate teams. You still have separate pipelines. But deployment tells a different story.

A new version of Service A requires an update in Service B. Service B depends on a change in Service C. Rollback becomes coordinated. A clean environment refuses to start unless services are deployed in a precise order.

You now have many services. But you no longer have independence.

The Real Problem Wasn’t Microservices

The problem wasn’t splitting the monolith. The problem was losing visibility of the system. In a monolith, the dependency graph is local. You can search it. You can reason about it. You can see the edges. In microservices, that graph becomes fragmented. It lives partly in code, partly in infrastructure files, partly in documentation, and partly in people’s heads.

Independence becomes assumed rather than verified. But independent deployment is not an intention. It is a graph property. If your deployment dependencies form a cycle, at least one service cannot evolve independently. You have created a distributed monolith — even if the code is physically separated. And you cannot detect that cycle by looking at a single repository. You must see the whole system.

The Paradox of Microservices

Microservices decentralize execution. But architecture must remain centralized in understanding. This does not mean centralizing control. It does not mean an architecture committee approving every change. It means maintaining a single, consistent view of how services truly connect.

Without that view:

• Transitive dependencies remain invisible.
• Deployment constraints accumulate silently.
• Impact analysis becomes guesswork.
• Coordination cost creeps back in.

What we needed was not more documentation. We needed a structural mechanism.

Distributed Ownership, Shared Reality

This is where the real challenge lies. If you centralize modeling in one team, you recreate a bottleneck. If you leave modeling entirely decentralized, the architecture drifts. The solution is to distribute the modeling itself — but synchronize the result.

Each team should own its service definition:

• What it depends on
• How it must be deployed
• What capabilities it exposes

But those local models must feed into a shared, continuously updated system graph. Architecture becomes a living structure, not a static diagram. If a new dependency introduces a circular deployment path — even across teams — it must be detected immediately. Not by policy. By topology.

Public Properties as First-Class Citizens

In most microservice environments, service contracts are scattered. API specs live in one place. Configuration assumptions live elsewhere. Deployment constraints are buried in scripts. Consumers depend on knowledge that is rarely explicit.

A change in one service can ripple silently through others.

By explicitly modeling public service properties — APIs, configuration requirements, deployment constraints, versioned capabilities — those properties become automatically visible to all declared consumers. The graph itself becomes the contract surface. When something changes, you don’t ask, “Who might be impacted?” You know. Because the relationships are structural.

Making Evolution Safer

The hardest part of microservices is not adding services. It is changing them. When a public capability evolves, or a deployment requirement shifts, multiple services may need to adapt. Without a synchronized model, this becomes a coordination exercise: meetings, messages, spreadsheets.

With a unified graph, impact becomes computable. Consumers are visible. Dependencies are explicit. Changes can propagate systematically rather than informally. The architecture stays aligned with reality. Not because someone updated a diagram. Because the system enforces coherence.

Preserving the Promise

We did not leave the monolith to replace one kind of coordination with another. We left it to scale. Microservices can absolutely scale organizations — but only if independence is structural, not assumed.

That requires:

• Explicit modeling of service relationships
• Validation of deployment topology
• Visibility of transitive dependencies
• Automatic synchronization of public properties
• Decentralize code.
• Decentralize ownership.
• But centralize structural truth.

Because in distributed systems, chaos does not come from having many services. It comes from not knowing how they truly connect. And once you lose sight of the graph, you lose independence.

That is the problem Cortex was built to solve — not by centralizing power, but by synchronizing architectural reality across the organization.

Cortex

Design your services once. Deploy them everywhere.

• Provide your email and a password, with at least 7 characters, 1 capital letter, 1 digit and 1 special character.
• Check that you have read the data policy and the terms and conditions
• Validate your registration
• You'll recieve an email with a link to confirm your email address

You will now start the onboarding process. To serve you the best we can, we need to know basic informations about your company. Please provied your company name and a phone number (optional).

We'd like to know more about you. Please provide your job title, firstname and lastname

Finaly, hit the Next button to activate your account and start with your free benefits

A registered user will get an email asking to accept the invitation. The link will be valid as long as you don't delete the invite.

An unregistered user will recieve an email asking to join the platform. The process is the same as the regular registration process, except that onve the onboarding in completed, the invites will be automatically processed and the user will immediately be enabled to collaborate on the projects.