framework-ignition-docker/README.md

Ignition + Docker Development Framework

Reusable scaffold for Ignition SCADA + Docker projects, designed to work with Claude Code as the AI development assistant.

First Consumer

PLC I/O Testing Platform — automated PLC I/O validation using JSON-defined test scenarios.

Stack

• Ignition 8.3 (Perspective, WebDev, OPC-UA, Git-native project storage)
• Docker Compose on Ubuntu 24
• Rockwell Allen-Bradley ControlLogix/CompactLogix
• PostgreSQL 16
• Traefik v3 (optional reverse proxy)
• Gitea for source control

First-Time Setup

Prerequisites

• Docker + Docker Compose installed on the host (Ubuntu 24 recommended)
• Git repo cloned to the host machine

Automated (recommended)

bash scripts/setup.sh

The script creates the proxy network, sets up ~/.config/ignition-dev/secrets.env, symlinks docker/.env to it, and scaffolds the gateway password file. Edit those two files, then jump to step 4 below.

Manual

1. Create the secrets file

cp docker/gw-secret/GATEWAY_ADMIN_PASSWORD.example docker/gw-secret/GATEWAY_ADMIN_PASSWORD
# Edit the file and set a real password — this file is gitignored
nano docker/gw-secret/GATEWAY_ADMIN_PASSWORD

2. Create the environment file

cp docker/.env.example docker/.env
# Edit values as needed (Ignition version, memory, hostname, Postgres password)
nano docker/.env

Key variables in .env:

Variable	Default	Description
IGNITION_VERSION	8.3.3	Ignition image version
GATEWAY_MAX_MEMORY	8192	Gateway JVM heap in MB
GATEWAY_NAME	framework	Gateway name shown in designer
GATEWAY_HOSTNAME	ignition.localhost	Public hostname (Traefik routing)
POSTGRES_PASSWORD	changeme	PostgreSQL password

3. Create the external Docker network

The stack uses an external proxy network (shared across projects). Create it once per Docker host:

docker network create proxy

This is a no-op if it already exists.

4. Build and start the stack

cd docker
docker compose build        # builds the custom Ignition image
docker compose up -d        # starts all services in background

5. Verify services are healthy

docker compose ps           # all services should show "healthy" or "running"
curl -s http://localhost:8088/StatusPing   # should return "RUNNING"

6. Open the gateway

• Ignition gateway: http://localhost:8088
• Traefik dashboard: http://localhost:8080
• Via hostname (requires local DNS or /etc/hosts): http://ignition.localhost

Note: On first boot the gateway skips the setup wizard (commissioning.json pre-commissions it). Log in with username admin and the password from gw-secret/GATEWAY_ADMIN_PASSWORD.

7. Connect Ignition Designer

Open Ignition Designer Launcher, add gateway at http://<host-ip>:8088, and open the Framework project. The project files in ignition/project/ are live-mounted — changes saved in Designer write directly to Git-tracked files.

---

Development

See CLAUDE.md for project directives, canonical patterns, and directory layout.

Directory Structure

├── CLAUDE.md              ← root directives (Claude Code reads this automatically)
├── scripts/               ← setup and utility scripts
├── docker/                ← Docker Compose stack and configs
├── ignition/              ← Ignition project (mounted into container)
├── testing/               ← test scenarios, runner, results
├── webdev/                ← WebDev API endpoint contracts
├── tools/                 ← Python 3.10+ external utilities
└── docs/                  ← project documentation

Each subdirectory contains its own CLAUDE.md with domain-specific rules.

License

Internal use only.