Pocket‑Lab provisions a full‑stack, self‑hosted AI laboratory on any fresh Linux host.
Everything – from reverse‑proxy, observability, vector and relational stores up to LLM tooling is bootstrapped with repeatable automation.

Contents

• Pocket-Lab 🧪
  • Stack overview
  • Key features
  • Repository map
  • Requirements
  • Quick start (Ansible path) 🚀
    • Developer workflow (Taskfile) 🛠️
    • Plain Docker Compose 🐳
  • Services & Configuration Reference 📝
    • Traefik Basic‑Auth 🔒
    • n8n 🔁
    • Open WebUI 🌐
    • RAGFlow 📚
    • Stirling PDF 📄
    • Ollama 🦙
    • MinIO ☁️
    • Secure-access layer - Tailscale 🔐
    • MySQL 🐬
    • Infinity ♾️
    • Valkey (Redis drop-in) 🐏
    • Elasticsearch 🔍
    • Portainer 🛠️
    • Prometheus 📊
    • Grafana 📈
    • Loki 📜
    • SMTP relay ✉️
    • Web search (Open WebUI + SearXNG) 🔎
    • No-Code Architects Toolkit 🧰
    • Typical workflows
    • Provisioning with Ansible
      • First-time setup (day-0 guide)
    • Private / no-public-IP deployments (localhost or tailnet)
      • Task catalogue
      • Variables you will likely change
      • Role overview
    • Table of all Variables
  • Contributing & CI hints
  • Release Process

• ✨ One code base – three ways to deploy

  1. Ansible – run task ansible_full to install Docker and start the stack.
  2. Go Task + Docker Compose – developer‑friendly shortcuts (task compose‑*) that mirror the authoritative stack assets into ./docker/.
  3. Plain Docker Compose – copy ansible/roles/pocket_lab/files/compose.yaml next to a hand‑crafted .env and run docker compose up -d.

• ✨ First run bootstrap for upstream projects without automated admin account creation
  Short‑lived helper containers/scripts create the very first administrator and disable sign‑up where the upstream image offers neither:

  Service	Bootstrap helper	Variables
  n8n	n8n-bootstrap → initial_admin_setup.sh	N8N_ADMIN_EMAIL, N8N_ADMIN_PASSWORD
  Open WebUI	openwebui-bootstrap → create_admin.py	OPENWEBUI_ADMIN_EMAIL, OPENWEBUI_ADMIN_PASSWORD
  RAGFlow	ragflow/entrypoint.sh → create_admin.py	RAGFLOW_ADMIN_EMAIL, RAGFLOW_ADMIN_PASSWORD

• 🔐 Secrets by design All credentials and tunables live in a single .env file. Ansible renders it from templates/.env.j2 – or – developers copy .env.template manually. A small guard script scripts/sync_env.py keeps both sources of truth in sync and regenerates docs/ENVIRONMENT.md.

• 🛡️ Secure defaults Traefik terminates TLS (Let’s Encrypt DNS‑01 via Cloudflare) and injects a Basic‑Auth middleware for every UI unless the upstream project has its own authentication.\

• Linux host with Docker and docker compose installed
• Python 3.11 or newer
• Optional: Go Task for the helper commands

1. Add your target server to the inventory

   cp ansible/inventory/hosts.yaml.template ansible/inventory/hosts.yaml

2. Set up the Python virtual‑env (installs Ansible + collections)

   task venv:init

3. Provision the lab

   task ansible_full

1. Mirror stack assets and generate the .env file

   task compose-prepare

2. Edit and set strong passwords, API keys and any secrets marked

   vim docker/.env

3. Launch the stack locally

   cd docker
   docker compose up -d

1. Copy the compose spec and create

   cp ansible/roles/pocket_lab/files/compose.yaml .
   cp .env.template .env

2. Edit the .env file and replace every default credential with a secure value before starting the stack.

   vim .env

3. Bring up the stack

   docker compose up -d

Note: this manual path skips Ansible – use for quick experiments only.

Pocket‑Lab ships with a demo hash (admin / admin) so the dashboards are reachable right away.
Generate your own credentials with:

htpasswd -nbB admin 'myStrongP@ssw0rd'

• Copy the full user:$2y$… string exactly as printed.
• In all deployment modes place it in single quotes to preserve the $ signs:
  • Docker Compose / Taskfile → in docker/.env:

Auth exceptions: UIs that already have their own authentication (e.g. Grafana, Open WebUI) are not protected by Traefik Basic-Auth. Grafana remains reachable without the middleware and uses its own login page.

```env
TRAEFIK_BASIC_AUTH='admin:$2y$…'
```

• Ansible → set basic_auth: 'admin:$2y$…' in either
  • ansible/roles/pocket_lab/defaults/main.yaml, or
  • a dedicated group_vars/<group>.yaml or host_vars/<host>.yaml file.

The lab bootstraps its n8n instance automatically. A short‑lived n8n-bootstrap container runs initial_admin_setup.sh before the main service starts. The script resets user management once and uses N8N_ADMIN_EMAIL and N8N_ADMIN_PASSWORD from the env file to create the global owner account. It marks the database so this runs only once. If the bootstrap fails the stack still starts but no owner will exist.

n8n is served through Traefik at https://n8n.${TRAEFIK_DOMAIN}. The env file wires this domain into WEBHOOK_URL, N8N_HOST and N8N_PROTOCOL (optionally N8N_EDITOR_BASE_URL) so OAuth callbacks use the correct HTTPS origin.

The openwebui-bootstrap container executes create_admin.py once before the actual service comes up. It creates or updates the administrator defined via OPENWEBUI_ADMIN_EMAIL and OPENWEBUI_ADMIN_PASSWORD. Registration behaviour is controlled through ENABLE_SIGNUP, the default role via DEFAULT_USER_ROLE and configuration persistence via ENABLE_PERSISTENT_CONFIG.

• Open WebUI is wired to Ollama via OLLAMA_BASE_URL (defaults to internal http://ollama:11434), OFFLINE_MODE=true by default (no version pings/online features), but Web Search is enabled out-of-the-box and points to the bundled SearXNG instance.

RAGFlow runs behind an internal nginx with Traefik handling the public endpoint. User sign‑up is disabled by default (REGISTER_ENABLED=0). On container startup create_admin.py ensures the admin account defined via RAGFLOW_ADMIN_EMAIL and RAGFLOW_ADMIN_PASSWORD exists and belongs to the default tenant. Visit https://ragflow.${TRAEFIK_DOMAIN} to access the UI.

Tune registration behaviour or credentials in .env or the corresponding Ansible defaults. RAGFlow talks to MySQL, MinIO and Valkey using the variables in the env‑file (MINIO_USER, MINIO_PASSWORD, REDIS_HOST, …).

If LLM_CHAT_MODEL points to a model your provider does not authorise, the admin bootstrap may fail. Before launching the stack set LLM_FACTORY and LLM_CHAT_MODEL to a locally served model (for example via Ollama) or leave them blank so RAGFlow uses its internal default.

The default language model backend is controlled via the user_default_llm block in service_conf.yaml. Override values such as LLM_FACTORY, LLM_API_KEY or LLM_CHAT_MODEL in your .env to point RAGFlow at a different provider or model.

Stirling PDF offers browser-based PDF manipulation at https://pdf.${TRAEFIK_DOMAIN}. Its own login is disabled by default (STIRLING_PDF_ENABLE_LOGIN=false) and access is protected through Traefik's Basic-Auth middleware. Set STIRLING_PDF_ENABLE_LOGIN=true to enable the application's sign-in page. Configuration and data persist in dedicated volumes.

Ollama runs the local language models used by the lab. The service exposes the standard API at https://ollama.${TRAEFIK_DOMAIN} and acts as the default LLM backend for Open WebUI and RAGFlow. On first start a short-lived ollama-bootstrap companion downloads all models listed in OLLAMA_PULL_MODELS so they are available locally. The variable accepts a space-separated list and defaults to llama3.1:8b deepseek-r1:7b qwen2.5-coder:7b bge-m3. The helper exits successfully if all models are already present so it is safe to rerun.

• Default pre-pulled models on first run: llama3.1:8b (general), deepseek-r1:7b (reasoning), qwen2.5-coder:7b (coding), plus bge-m3 embeddings.

The lab ships with a MinIO server used as the S3 backend for other services. Traefik simply forwards https://minio.${TRAEFIK_DOMAIN} to the MinIO container, which serves both the API and the web console.

Key variables:

• MINIO_ROOT_USER / MINIO_ROOT_PASSWORD – console credentials.
• MINIO_SERVER_URL – external URL of the API and console (defaults to the Traefik hostname).

If you customise TRAEFIK_DOMAIN, adjust MINIO_SERVER_URL accordingly so the dashboard can reach the backend.

Full variable reference lives in:

• ansible/roles/pocket_lab/defaults/main.yaml

Pocket‑Lab ships with a lightweight Tailscale container that runs in host‑network mode, advertises the Docker bridge subnet and enables Tailscale SSH.

1. Create an Auth Key in the Tailscale admin console → Keys → “Reusable, pre‑authorized”.
2. Put it in .env as TS_AUTHKEY.
3. (Optional) change DOCKER_BRIDGE_SUBNET if you run multiple labs or the default ‑ 172.20.0.0/16 – collides with an existing network.

# .env (excerpt)
TS_AUTHKEY   = tskey-auth-ABC123...
DOCKER_BRIDGE_SUBNET = 172.20.0.0/16

No other Tailscale options need tweaking – advanced users can set TS_EXTRA_ARGS in docker-compose.yaml.

When the stack comes up the tailscale service automatically:

• joins your tailnet and appears as pocket‑lab.tail.ts.net
• advertises the subnet defined by DOCKER_BRIDGE_SUBNET
• enables Tailscale SSH on the host and every container (via --ssh)

RAGFlow stores its relational data in a standalone MySQL container. Set MYSQL_ROOT_PASSWORD for the root account and adjust MYSQL_DATABASE to change the default schema. MYSQL_PORT and MYSQL_HOST control the exposed port and container name.

Infinity provides the vector index used by RAGFlow. The included infinity_conf.toml configures storage paths while the ports are customisable through INFINITY_THRIFT_PORT, INFINITY_HTTP_PORT and INFINITY_PSQL_PORT. The service registers under INFINITY_HOST.

Valkey offers a Redis-compatible key–value store. Protect it with REDIS_PASSWORD and change the image or port via REDIS_VERSION and REDIS_PORT.

Elasticsearch indexes all documents for RAGFlow. Modify ES_PASSWORD for the elastic user and ES_PORT for the HTTP API. ES_HOST chooses the hostname while MEM_LIMIT limits container memory usage.

Portainer exposes a small Docker dashboard at https://portainer.${TRAEFIK_DOMAIN} protected by Traefik basic-auth. Update PORTAINER_VERSION or change the UI port with PORTAINER_PORT.

Prometheus collects metrics from node-exporter and the stack. The image tag is set via PROMETHEUS_VERSION. Additional scrape targets can be defined in prometheus/prometheus.yaml.

Grafana visualises metrics at https://grafana.${TRAEFIK_DOMAIN}. Initial credentials come from GRAFANA_ADMIN_USER and GRAFANA_ADMIN_PASSWORD. Use GRAFANA_VERSION to upgrade.

Loki stores container logs that Grafana can query. Change LOKI_VERSION if you need a different release.

A lightweight Postfix relay lets services send mail. Set SMTP_IMAGE to choose the container, SMTP_PORT for the listening port and SMTP_SSL to toggle TLS. The hostname is derived from SMTP_HOST.

Pocket-Lab ships a private SearXNG instance (internal-only) and wires it into Open WebUI as the default web search backend. JSON output is enabled and rate limiting is disabled for private use.

Defaults (override in .env / Ansible vars):

# endpoints & privacy
WEBUI_URL=https://chat.<your-domain>
OFFLINE_MODE=true
ENABLE_VERSION_UPDATE_CHECK=false
OLLAMA_BASE_URL=http://ollama:11434

# web search
ENABLE_WEB_SEARCH=true
WEB_SEARCH_ENGINE=searxng
SEARXNG_QUERY_URL=http://searxng:8080/search?q=<query>&format=json
WEB_SEARCH_RESULT_COUNT=5
WEB_SEARCH_CONCURRENT_REQUESTS=2
ENABLE_SEARCH_QUERY_GENERATION=false

Why SearXNG? It avoids public-instance rate limits and API blocks while keeping search local to your stack. Open WebUI discovers it through WEB_SEARCH_ENGINE=searxng + SEARXNG_QUERY_URL. See Open WebUI env config & tutorial. Also ensure SearXNG exposes JSON (search.formats: [html, json]). :contentReference[oaicite:2]{index=2}

Internal toolkit service available on the private network at http://ncat:8080. It targets the bundled MinIO (http://minio:9000) and stores data in the pocket_lab bucket by default. Configure it with NCA_VERSION, NCA_API_KEY, NCA_S3_ENDPOINT, NCA_S3_BUCKET, NCA_S3_ACCESS_KEY and NCA_S3_SECRET_KEY.

# list all lab containers – works from any device in the tailnet
tailscale status

# SSH into the host (root)
tailscale ssh root@pocket-lab

# SSH into a container by name
tailscale ssh root@mysql

# Expose a local dev port to the tailnet for 30 min
tailscale funnel 4040 --timeout 30m

The repository bundles a small automation layer under ansible/. After preparing your .env and inventory you only need two commands:

task venv:init  # install Ansible and required collections
task ansible_full  # deploy the stack

Run task ansible_deploy to execute the play directly.

You can deploy with almost all defaults. The only values you typically must provide are:

• cloudflare_api_token (for automatic TLS via DNS-01), and/or
• ts_authkey (if you want private tailnet access).

For full control over passwords/users/ports, copy the role defaults into host-specific vars and override only what you need:

mkdir -p ansible/host_vars
cp ansible/roles/pocket_lab/defaults/main.yaml ansible/host_vars/genai-vm.yaml
# edit ansible/host_vars/genai-vm.yaml and change only the vars you care about

You can also use group_vars/<group>.yaml if you target multiple machines.

1) Inventory

cp ansible/inventory/hosts.yaml.template ansible/inventory/hosts.yaml
# set ansible_host and ansible_user

2) Install Ansible toolchain

task venv:init

3) Deploy

task ansible_full

4) Local/self-deploy (no SSH) If you run Ansible on the target itself:

# ansible/inventory/hosts.yaml
genai_servers:
  hosts:
    localhost:
      ansible_connection: local
      ansible_python_interpreter: /usr/bin/python3
      ansible_user: root

Then task ansible_full.

Idempotent helpers

task ansible_check   # dry-run
task ansible_deploy  # re-run deploy play

You can run Pocket-Lab on a host with no public IP and still get HTTPS + Traefik routing.

A) DNS-01 + /etc/hosts (recommended)

1. Set a Cloudflare token (CLOUDFLARE_DNS_API_TOKEN / cloudflare_api_token).
2. Deploy the stack.
3. On the client you browse from (or on the server itself), add host entries mapping service names to the server IP (use 127.0.0.1 when browsing on the server):

127.0.0.1  traefik.${TRAEFIK_DOMAIN} grafana.${TRAEFIK_DOMAIN} \
           prometheus.${TRAEFIK_DOMAIN} portainer.${TRAEFIK_DOMAIN} \
           n8n.${TRAEFIK_DOMAIN} chat.${TRAEFIK_DOMAIN} \
           ragflow.${TRAEFIK_DOMAIN} minio.${TRAEFIK_DOMAIN} \
           ollama.${TRAEFIK_DOMAIN}

ACME DNS-01 only checks TXT records, so you don’t need public A/AAAA records.

B) Tailscale-only access

1. Set TS_AUTHKEY / ts_authkey and deploy.
2. Find the host’s tailnet IP or MagicDNS name (tailscale status / tailscale ip).
3. Add /etc/hosts on your client mapping the same service names to that tailnet IP.

Sanity checks

curl -I -k -H "Host: grafana.${TRAEFIK_DOMAIN}" https://127.0.0.1

For deep‑links and automatic change‑tracking the same table is regenerated in docs/ENVIRONMENT.md whenever scripts/sync_env.py --docs is executed.

• Use two‑space YAML indentation and keep block‑comment separators.
• Run a quick syntax check before committing:
  ansible-playbook --syntax-check ansible/site.yaml && docker compose -f ansible/roles/pocket_lab/files/compose.yaml config
• Keep this README and docs/ENVIRONMENT.md up‑to‑date when touching variables or behaviour.

We follow SemVer. Tag releases and publish notes.

git tag -a v0.1.0 -m "Pocket-Lab v0.1.0 — first public release"
git push origin v0.1.0