# 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.**