Atlas Lab is a localhost-first self-hosted platform made of a Node.js/TypeScript CLI, a layered Docker Compose stack, and an operational React dashboard served by Caddy.

It provides a core collaboration layer with GitLab CE, plus optional AI and development layers. Everything is reachable through dedicated HTTPS ports on localhost, with persistent state stored in Docker volumes.

• 🧭 Overview
• 🏗️ Architecture
• 🔌 Services, Ports, and URLs
• 🕸️ Docker Networks
• 💾 Persistence
• 🧰 Host Requirements
• ⚙️ Central Configuration
• 🚀 Quick Start
• 🧪 CLI Workflows
• 🖥️ Atlas Dashboard
• 📦 Backup and Restore
• 🔐 Default Credentials
• 🧩 Adding Services
• 🗂️ Repository Layout
• 🩺 Troubleshooting
• 🛡️ Security Notes
• 📚 Official References
• 📄 License

• Always-on core layer with Atlas Dashboard and GitLab CE.
• Optional AI LLM layer with Open WebUI, Ollama, and n8n.
• Optional workbench layer with browser-based Node and Python environments plus shared PostgreSQL.
• HTTPS-only browser ingress on localhost.
• Self-contained npm package that can run without a local repository checkout.
• Image and volume backup workflows through the CLI.

• no internal DNS requirement
• no hosts file edits
• no disposable init containers in Compose
• no hard dependency on a checked-out repo after packaging
• one operational flow for startup, bootstrap, diagnostics, backup, and restore

Atlas Lab is split into three explicit layers.

The current topology uses localhost plus dedicated HTTPS ports. That keeps the stack predictable on a single machine and avoids local DNS maintenance.

Bootstrap is handled by the TypeScript CLI.

The CLI:

• starts Docker Compose
• runs host preflight checks
• validates Compose and repository assets
• aligns the GitLab root account after GitLab is ready
• aligns the n8n owner account when the AI LLM layer is enabled
• reconciles Ollama models when the AI LLM layer is enabled

GitLab CE initializes its root account during first container boot through the GitLab Docker/Omnibus configuration.

All browser entry points are exposed over HTTPS on localhost.

Operational rules:

• browsers always go through Caddy
• optional layers never start implicitly
• host-side PostgreSQL clients must use localhost:15432

The gateway remains the only public browser entry point for web services.

Atlas Lab uses named Docker volumes for runtime state.

Core volumes:

• gateway-certs

• gateway-config

• gateway-site

• gateway-data

• gitlab-config

• gitlab-logs

• gitlab-data Optional layer volumes:

• ollama-data

• n8n-data

• open-webui-data

• postgres-dev-data

• Node and Python workbench home/workspace volumes

Recreating containers does not wipe state. Removing volumes does.

When migrating from an older local run, stop the stack with:

npm run dev -- down

The current Compose files no longer reference removed core services. Any older unused volumes remain on disk until you inspect and delete them manually.

Required software:

• Docker Engine with Docker Compose v2
• Node.js >= 20
• npm

AI LLM requirements:

• NVIDIA GPU
• working nvidia-smi
• Docker configured with NVIDIA GPU support

Recommended resources:

• CPU: 4 vCPU or better
• RAM: 8 GB minimum, 12-16 GB preferred
• disk: 20 GB free or more
• VRAM: 8 GB or more for comfortable Ollama usage

Ports that should be free:

• 8443
• 8444
• 8446
• 8447
• 8450
• 8451
• 8453
• 15432 when workbench is enabled

The main runtime configuration lives in:

• env/lab.env

Key variables include:

• LAB_HTTPS_PORT, GITLAB_HTTPS_PORT
• OPENWEBUI_HTTPS_PORT, OLLAMA_HTTPS_PORT, N8N_HTTPS_PORT
• NODE_DEV_HTTPS_PORT, PYTHON_DEV_HTTPS_PORT, POSTGRES_DEV_HOST_PORT
• GITLAB_EXTERNAL_URL, GITLAB_URL
• GITLAB_ROOT_USERNAME, GITLAB_ROOT_PASSWORD, GITLAB_ROOT_EMAIL
• N8N_ROOT_EMAIL, N8N_ROOT_PASSWORD
• OLLAMA_CHAT_MODEL, OLLAMA_EMBEDDING_MODEL, OLLAMA_RUNTIME_MODELS

Rule of thumb:

• change ports, versions, credentials, and models in env/lab.env
• change routing and runtime content in config/gateway/templates/
• change CLI behavior in src/

Check prerequisites:

docker version
docker compose version
node --version
npm --version

Install dependencies:

npm install

Start the core layer:

npm run dev -- up

Start core plus AI LLM:

npm run dev -- up --with-ai-llm

Start core plus workbench:

npm run dev -- up --with-workbench

Start the full lab:

npm run dev -- up --with-ai-llm --with-workbench

Run health checks:

npm run dev -- doctor --smoke
npm run dev -- doctor --with-ai-llm --smoke
npm run dev -- doctor --with-workbench --smoke

Stop the lab:

npm run dev -- down

GitLab CE can take several minutes to finish its first boot. The CLI bootstrap also aligns the configured root account after GitLab is healthy, so rerunning atlas-lab bootstrap refreshes the root password stored in env/lab.env.

Self-contained packaging:

npm run pack:local
npm install -g .\cli-node-docker-atlas-lab-<version>.tgz
atlas-lab status

The dashboard frontend lives in:

• apps/atlas-dashboard

Responsibilities:

• visualize layer state
• surface operational links
• expose local markdown briefings
• show credentials and runtime notes
• support it/en localization

Local dashboard development:

npm run dev:atlas-dashboard

Atlas Lab supports backup and restore for Docker images and Docker volumes.

Examples:

npm run dev -- save-images --with-ai-llm --with-workbench
npm run dev -- restore-images --input .\backups\images\atlas-lab-images.tar.gz
npm run dev -- down
npm run dev -- save-volumes --with-ai-llm --with-workbench
npm run dev -- restore-volumes --input .\backups\volumes\atlas-lab-volumes.tar.gz

Bootstrap is idempotent for GitLab CE and the optional AI LLM services.

These credentials are intended for trusted local environments and are configurable through env/lab.env.

For desktop PostgreSQL clients:

• host: localhost
• port: 15432
• database: lab
• username: postgres
• password: RootPostgresDev!2026

Use the same layered flow when adding, removing, or moving services. The tag describes the runtime contract, and the emoji keeps the intent visible in notes, issues, and commits.

1. Add port, URL, image version, credentials, and secrets in env/lab.env.
2. Add the service, volumes, depends_on, and networks in infra/docker/compose.yml.
3. Add the HTTPS route in config/gateway/templates/Caddyfile.template.
4. Add required template variables in infra/docker/images/gateway/bootstrap-gateway.sh.
5. Add runtime payload fields in config/gateway/templates/runtime/lab-config.json.template when the dashboard needs them.
6. Update dashboard schema, view-model builders, locale files, and network map nodes if the service should appear in the UI.
7. Update host port preflight, smoke checks, tests, README tables, and content templates.

1. Add the service in infra/docker/compose.ai-llm.yml.
2. Publish browser/API routes through gateway-ai-llm only.
3. Keep CLI behavior behind --with-ai-llm.
4. Add bootstrap and smoke checks only when AI LLM env validation passes.
5. Update dashboard optional-layer cards so disabled services remain visibly optional instead of pretending to be online.

1. Add the service in infra/docker/compose.workbench.yml.
2. Route browser workspaces through gateway-workbench.
3. Add host port preflight only for ports published to the host, such as desktop database access.
4. Add dashboard cards or briefings only for workflows users directly open or inspect.

1. Keep the service on an internal network.
2. Add named volumes for persistent state.
3. Add health checks when other services depend on readiness.
4. Do not add public Caddy routes or dashboard cards unless the service becomes user-facing.

Key files:

• package.json
• env/lab.env
• infra/docker/compose.yml
• infra/docker/compose.ai-llm.yml
• infra/docker/compose.workbench.yml
• config/gateway/templates/Caddyfile.template
• config/gateway/templates/runtime/lab-config.json.template
• infra/docker/images/gateway/bootstrap-gateway.sh

Expected behavior. The lab uses a self-signed certificate for localhost.

Certificate download URL:

https://localhost:8443/assets/lab.crt

One of the configured lab ports is occupied or excluded by the system.

atlas-lab status
docker ps --format "table {{.Names}}\t{{.Ports}}\t{{.Status}}"

GitLab CE runs its Omnibus reconfiguration on first boot and can take several minutes before https://localhost:8444/ is ready. Check status with:

docker compose --env-file env/lab.env -f infra/docker/compose.yml ps gitlab
docker compose --env-file env/lab.env -f infra/docker/compose.yml logs -f gitlab

This is usually a Docker daemon GPU pass-through issue.

nvidia-smi -L
docker info

Workbenches are not part of the core layer. Start them explicitly:

npm run dev -- up --with-workbench

Atlas Lab is intended for:

• local use
• technical lab environments
• trusted networks
• development and prototyping

It is not an internet-facing production deployment hardened out of the box.

For stronger hardening:

• move secrets into an external secret-management system
• replace the default certificate with one signed by an internal CA
• tighten network segmentation further
• define recurring backup policies
• audit logs and default credentials

• Docker installation: https://docs.gitlab.com/ee/install/docker/
• Docker configuration: https://docs.gitlab.com/ee/install/docker/configuration.html
• Omnibus NGINX settings: https://docs.gitlab.com/omnibus/settings/nginx.html

• Compose startup order: https://docs.docker.com/compose/how-tos/startup-order/
• Compose networks: https://docs.docker.com/reference/compose-file/networks/
• Docker networking drivers: https://docs.docker.com/engine/network/drivers/

• Caddyfile concepts: https://caddyserver.com/docs/caddyfile
• Reverse proxy: https://caddyserver.com/docs/caddyfile/directives/reverse_proxy

• Self-hosted user management: https://docs.n8n.io/hosting/configuration/user-management-self-hosted/
• Docker install: https://docs.n8n.io/hosting/installation/docker/

• Environment configuration: https://docs.openwebui.com/getting-started/env-configuration/

• FAQ: https://docs.ollama.com/faq
• API reference: https://github.com/ollama/ollama/blob/main/docs/api.md

• Official docs: https://coder.com/docs/code-server/latest

This project is distributed under the MIT license.