Local Docker infrastructure for testing Brik pipelines end-to-end: write brik.yml, push to GitLab or Gitea, watch the pipeline run on real CI platforms.

Brik needs real CI/CD platforms to validate its shared libraries and runtime. Briklab provides that infrastructure locally via Docker Compose -- no cloud accounts, no shared servers.

• One command to set up everything (init)
• GitLab CE + Runner + Registry for GitLab CI pipelines
• Gitea + Jenkins for Jenkins pipelines
• Nexus 3 CE for artifact publishing (npm, Maven, PyPI, NuGet, Docker, raw)
• E2E pipeline testing with automated scenario validation on both platforms
• Managed by a Bash CLI (scripts/briklab.sh)

For internal architecture details, see docs/architecture.md.

• Docker Desktop (18 GB RAM recommended)
• jq (brew install jq)

Add to /etc/hosts:

127.0.0.1  gitlab.briklab.test registry.briklab.test
127.0.0.1  gitea.briklab.test jenkins.briklab.test argocd.briklab.test
127.0.0.1  nexus.briklab.test

Add to Docker Desktop (Settings > Docker Engine):

{
  "insecure-registries": [
    "registry.briklab.test:5050",
    "nexus.briklab.test:8082"
  ]
}

./scripts/briklab.sh init

GitLab takes 3-5 minutes on first start. Jenkins builds a custom Docker image on first start. Nexus takes 2-3 minutes. The script waits automatically.

macOS note: the registry uses port 5050 because AirPlay Receiver occupies port 5000.

Default credentials are defined in .env. Modify them before the first init.

Setup creates 6 hosted repositories for artifact publishing:

Note: Nexus CE does not support the Cargo registry protocol natively. Rust crate publishing uses cargo publish --dry-run for validation, with Docker as the actual publish target.

Platform is required: --gitlab or --jenkins. All other flags are identical.

# Day 1 - Full setup
./scripts/briklab.sh init                    # First time setup (~5 min)
./scripts/briklab.sh test --gitlab --all     # Run GitLab E2E suite
./scripts/briklab.sh test --jenkins --all    # Run Jenkins E2E suite
./scripts/briklab.sh stop                    # Done for the day

# Day N
./scripts/briklab.sh start                   # Restart (fast, data preserved)
./scripts/briklab.sh test --gitlab           # Quick GitLab smoke test
./scripts/briklab.sh test --jenkins          # Quick Jenkins smoke test
./scripts/briklab.sh stop                    # Done

Each GitLab E2E scenario pushes a test project to briklab GitLab, triggers a pipeline, and validates that specific jobs pass.

Jenkins E2E testing pushes the Brik shared library and a test project to Gitea, then triggers a Jenkins pipeline via the REST API.

The Jenkins pipeline runs the full Brik fixed flow:

Init -> Release -> Build -> Quality & Security -> Test -> Package -> Deploy -> Notify

Jenkins is configured via CasC (Configuration as Code) with:

• The Brik Jenkins Shared Library loaded from Gitea (brik/brik repo)
• A node-minimal pipeline job that pulls from Gitea (brik/node-minimal repo)

# Run the Jenkins E2E pipeline
./scripts/briklab.sh test --jenkins

# Run a specific job (default: node-minimal)
./scripts/briklab.sh test --jenkins node-minimal

Test project fixtures live in test-projects/. Each has a brik.yml and platform-specific CI config (.gitlab-ci.yml for GitLab, Jenkinsfile for Jenkins).

Runner images are selected automatically by the init job based on project.stack and project.stack_version in brik.yml. The init job resolves the image and propagates it via dotenv to downstream jobs. Images are published at ghcr.io/getbrik/brik-runner-<stack>:<version>.

GitLab won't start -- Check Docker Desktop has at least 18 GB RAM allocated. First start takes 3-5 minutes. Check logs: ./scripts/briklab.sh logs gitlab

Runner errors (runner_system_failure / image_pull_failure) -- Verify helper_image is present in the runner's config.toml. Check logs: ./scripts/briklab.sh logs runner. If needed, re-run ./scripts/briklab.sh setup.

Port 5000 already in use (macOS) -- AirPlay Receiver occupies port 5000. Briklab uses 5050 by default. To free 5000: Settings > General > AirDrop & Handoff > AirPlay Receiver, uncheck.

Registry unreachable -- Verify "insecure-registries": ["registry.briklab.test:5050"] in Docker Desktop settings. Test: curl http://registry.briklab.test:5050/v2/

Jenkins CasC errors -- Check ./scripts/briklab.sh logs jenkins for Configuration-as-Code errors. Common issue: plugin not installed. Verify images/jenkins/plugins.txt includes all required plugins. To reload CasC without restarting Jenkins, use the jenkins_reload_casc helper in briklab.sh (only works for CasC YAML changes; env var changes require a full restart).

Jenkins pipeline can't find Brik library -- The Brik shared library must be pushed to Gitea before triggering a pipeline. Run ./scripts/briklab.sh setup to ensure Gitea is configured, then push repos with the E2E test command.

Gitea shows install page -- On first start, Gitea requires initial installation. The setup script handles this automatically. If it fails, check logs: ./scripts/briklab.sh logs gitea

Nexus slow to start -- First start takes 2-3 minutes (JVM + plugin initialization). The healthcheck has a 180s start_period. Check logs: ./scripts/briklab.sh logs nexus

Nexus Docker push fails (HTTP) -- Add "nexus.briklab.test:8082" to insecure-registries in Docker Desktop settings. The Nexus Docker registry uses HTTP, not HTTPS.

Nexus repository creation fails -- If setup is run before Nexus is fully ready, repository creation may fail. Wait for the healthcheck to pass, then re-run: ./scripts/briklab.sh setup

For the complete list of known issues and solutions, see docs/architecture.md - Known Gotchas.

# Stop containers (data preserved)
./scripts/briklab.sh stop

# Delete all data and volumes (irreversible, requires confirmation)
./scripts/briklab.sh clean

# Full removal: after clean, remove Docker images manually
docker rmi gitlab/gitlab-ce:18.10.1-ce.0 gitlab/gitlab-runner:alpine3.21-bleeding registry:3.0
docker rmi gitea/gitea:1.25.5-rootless
docker rmi briklab-jenkins  # custom-built Jenkins image
docker rmi sonatype/nexus3:3.90.2-alpine
docker network rm brik-net 2>/dev/null

• GitLab CE + Runner + Registry
• Gitea + Jenkins (CasC + Job DSL)
• Nexus 3 CE -- artifact publishing (npm, Maven, PyPI, NuGet, Docker, raw)
• Automated init with smoke tests
• E2E pipeline testing -- GitLab (18 scenarios: node, python, java, rust, dotnet)
• E2E pipeline testing -- Jenkins (node-minimal)
• Security stage E2E
• Deploy stage E2E
• Error scenario E2E (build fail, test fail, invalid config)
• Complete E2E scenarios with Nexus artifact verification
• k3d + ArgoCD integration

• Brik -- the portable CI/CD pipeline system
• Architecture -- how Briklab works internally

MIT