DataOps-platform/docs/superpowers/plans/2026-07-16-local-docker-test-stack.md

Local Docker Test Stack Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [x]) syntax for tracking.

Goal: Build and verify a fully local, disposable DataOps Platform test stack that cannot fall back to production data services.

Architecture: Docker Compose runs frontend, backend, PostgreSQL, Neo4j, MinIO and n8n on one isolated network with named volumes and explicit health checks. The backend image is built only from app/; Nginx serves the Vue production bundle and proxies /api/; PostgreSQL initializes current source DDL and a local-only test user.

Tech Stack: Docker Compose, Python 3.11, Gunicorn, Flask, Node.js 24, Vue 2, Nginx, PostgreSQL 16, Neo4j 5, MinIO, n8n.

---

Task 1: Add isolation contract tests

Files:

• Create: tests/test_local_docker_contract.py

• [x] Step 1: Write tests that require all seven services, explicit local URLs, health checks, named volumes, and no production fallback strings.

• [x] Step 2: Run python -m pytest tests/test_local_docker_contract.py -q and confirm it fails because Docker files do not exist.

• [x] Step 3: Keep the test focused on static safety contracts so it runs without Docker.

Task 2: Remove n8n production fallback credentials

Files:

• Modify: app/config/config.py
• Modify: app/core/data_factory/n8n_client.py
• Modify: tests/test_n8n_client_config.py

• Regenerate: deployment/app/ through deployment/sync_release.sh

• [x] Step 1: Change tests to assert no committed production n8n URL or token exists and placeholder/missing configuration stays unset.

• [x] Step 2: Run python -m pytest tests/test_n8n_client_config.py -q and confirm the old fallback behavior fails the test.

• [x] Step 3: Make N8N_API_URL and N8N_API_KEY environment-only; raise a clear N8nClientError before an HTTP call when either is missing.

• [x] Step 4: Run the n8n configuration tests and sync the generated deployment copy.

Task 3: Add backend and frontend images

Files:

• Create: .dockerignore
• Create: deploy/docker/backend.Dockerfile
• Create: deploy/docker/frontend.Dockerfile

• Create: deploy/docker/nginx.conf

• [x] Step 1: Build the backend from Python 3.11 slim, install requirements.txt, copy only application runtime files, and run Gunicorn on 5500.

• [x] Step 2: Build the frontend with Node 24 and npm ci, then copy dist/ into Nginx.

• [x] Step 3: Configure SPA fallback and /api/ proxying without rewriting the API prefix.

Task 4: Add deterministic local data bootstrap

Files:

• Create: deploy/docker/postgres/init/000-init.sql
• Create: deploy/docker/postgres/init/010-local-test-user.sql

• Reuse: database/*.sql

• [x] Step 1: Create the n8n database and include each current source DDL file with absolute \ir paths.

• [x] Step 2: Create the legacy-compatible local test users table and seed only admin / admin123, clearly marked local-only.

• [x] Step 3: Verify initialization by querying all expected tables after the stack starts.

Task 5: Add Compose and operator commands

Files:

• Create: deploy/docker/docker-compose.yml
• Create: deploy/docker/.env.example

• Create: deploy/docker/README.md

• [x] Step 1: Define seven isolated services, explicit environment variables, health checks, named volumes and fixed local ports.

• [x] Step 2: Add a one-shot MinIO client service that creates dataops-bucket.

• [x] Step 3: Document build/start/status/logs/stop/reset commands and the local URLs.

• [x] Step 4: Run docker compose config and scan the rendered configuration for production addresses.

Task 6: Build and verify the running stack

Files:

• Update: deploy/docker/README.md

• Update: this plan's checkboxes

• [x] Step 1: Run docker compose -f deploy/docker/docker-compose.yml up -d --build.

• [x] Step 2: Poll docker compose ps until dependencies and applications are healthy or capture failing logs.

• [x] Step 3: Verify frontend, backend health, n8n health, PostgreSQL tables and MinIO bucket.

• [x] Step 4: Run Python tests, frontend production build, git diff --check, and the Docker isolation string scan.

• [x] Step 5: Record image versions and actual verification results in the local environment guide.