RBAC-Lite Local Docker Environment and Branch Recovery Case Study

Summary

This document describes the implementation, validation and cleanup of the local Docker Compose test environment for the RBAC-Lite WordPress plugin.

The work added a local WordPress + MariaDB environment under dev-environment/, documented Docker Desktop usage, validated the local stack, improved the MariaDB healthcheck, and resolved a branch-history issue safely using cherry-pick analysis instead of merging a stale branch.

The case demonstrates controlled local development, Docker Compose validation, localhost-only service exposure, documentation discipline, Git branch hygiene and safe recovery from potentially dangerous branch divergence.

Repository

Repository:

Jonnenpijonne/RBAC-Lite

Relevant branch history included:

docker/local-rbac-lite-test-env
fix/mariadb-healthcheck-clean
main

Final state:

branch: main
working tree: clean
origin/main: up to date
obsolete local branches: deleted
stale remote-tracking branches: pruned

What was added

A local Docker Compose test environment was added under:

dev-environment/

The environment includes:

dev-environment/
├── docker-compose.yml
├── .env.example
├── README.md
├── DOCKER_DESKTOP.md
└── scripts/
    └── reset-local.sh

The environment runs:

WordPress + MariaDB

The RBAC-Lite plugin directory is mounted into WordPress from:

../sadepois-core

The WordPress service is bound to localhost only:

127.0.0.1:8080

This makes the environment suitable for local plugin validation without exposing WordPress publicly.

Safety scope

The work was intentionally scoped as local development support only.

The following were not changed:

plugin logic
production deployment configuration
root validation logic
real secrets
production data
Kubernetes configuration
Docker Hub publishing

The local environment uses placeholder credentials only through .env.example.

The documentation makes clear that these values are local-only placeholders and not production secrets.

Docker Compose healthcheck improvement

The MariaDB healthcheck was improved from a generic ping-style check to a MariaDB-specific credential-based readiness check.

Final healthcheck:

healthcheck:
  test: ["CMD-SHELL", "mariadb-admin ping -h 127.0.0.1 -u$${MYSQL_USER} -p$${MYSQL_PASSWORD} --silent"]
  interval: 10s
  timeout: 5s
  retries: 10
  start_period: 30s

The obsolete top-level Compose version line was also removed:

version: '3.9'

Why the healthcheck was changed

The previous healthcheck only verified that the database process responded at a basic level.

The improved check is stronger because it verifies that MariaDB is ready to accept authenticated local connections using the configured local database credentials.

This reduces race-condition risk where WordPress starts before the database is actually ready.

The start_period gives MariaDB time to initialize before healthcheck failures are counted.

The result is a more reliable local development environment.

Validation performed

The local environment was validated with Docker Compose.

Validation steps included:

docker compose -p rbac-lite-local \
  -f dev-environment/docker-compose.yml \
  --env-file dev-environment/.env.example \
  config

docker compose -p rbac-lite-local \
  -f dev-environment/docker-compose.yml \
  --env-file dev-environment/.env.example \
  up -d

docker compose -p rbac-lite-local \
  -f dev-environment/docker-compose.yml \
  --env-file dev-environment/.env.example \
  ps

Validation result:

docker compose config: passed
MariaDB container: healthy
WordPress container: healthy
WordPress port binding: 127.0.0.1:8080
obsolete version warning: removed

Git branch issue

During cleanup, the old feature branch was compared against main:

git log --oneline main..docker/local-rbac-lite-test-env
git diff --stat main..docker/local-rbac-lite-test-env

The diff showed that the old branch would have removed files that already existed in main, including documentation and local validation evidence.

The diff included hundreds of deletions.

This was treated as a warning sign.

The branch was not merged.

Cherry-pick recovery

Instead of merging the stale branch, only the desired healthcheck commit was tested through a clean cherry-pick approach.

A clean branch was created from main:

git checkout main
git pull --ff-only origin main
git checkout -b fix/mariadb-healthcheck-clean
git cherry-pick 5b4cb9a

The cherry-pick turned out to be empty:

The previous cherry-pick is now empty
nothing to commit, working tree clean

This proved that the healthcheck fix already existed in main.

The cherry-pick was skipped:

git cherry-pick --skip

The temporary branch was then removed.

Final cleanup

The repository was returned to a clean main state.

Cleanup commands:

git checkout main
git branch -D fix/mariadb-healthcheck-clean
git branch -D docker/local-rbac-lite-test-env
git remote prune origin

Final verification:

git branch --show-current
git status
git log --oneline -5
git branch -a | grep docker

Final state:

main
working tree clean
origin/main up to date
obsolete branches removed
stale remote references pruned

Recent main history included:

7069396 docs: add Docker Desktop manager workflow (#7)
1c344f6 docs: add local Docker validation evidence (#6)
3dff70a docs: add local Docker validation evidence (#5)
a9d9f67 fix: improve local Docker environment validation (#4)
689ac78 Docker/local rbac lite test env (#3)

What this demonstrates

This work demonstrates more than simply adding Docker Compose.

It demonstrates:

local-first development environment design
Docker Compose service orchestration
localhost-only exposure
database readiness validation
safe placeholder credential handling
WordPress plugin test setup
manual validation documentation
Docker Desktop workflow documentation
Git branch hygiene
safe cherry-pick recovery
avoidance of stale-branch merge risk
controlled scope management

Key lesson

The most important engineering decision was not technical implementation alone.

The important decision was recognizing that the old feature branch had become stale relative to main.

Instead of merging it and risking deletion of newer documentation and evidence files, the desired change was isolated and tested with cherry-pick.

When the cherry-pick was empty, it confirmed that the intended fix was already present in main.

This avoided unnecessary commits and prevented branch-history damage.

Portfolio framing

This is a useful portfolio example because it shows practical infrastructure and governance thinking at a small but realistic scale.

The value is not that the environment is complex.

The value is that it is controlled, documented, locally reproducible, safely exposed, validated, and cleaned up correctly.

Concise interview framing:

In the RBAC-Lite project, I added a local Docker Compose test environment for a WordPress access-control plugin. The environment runs WordPress and MariaDB locally, mounts the plugin into WordPress, binds access to localhost only, and documents validation and reset steps. I also improved the MariaDB healthcheck to verify actual database readiness with configured local credentials. During cleanup, I detected that an old branch would have removed newer documentation from main, so I avoided merging it and used cherry-pick analysis to confirm that the desired fix was already present. This kept the repository clean and avoided accidental regressions.

Public/private boundary

This document is suitable as a public portfolio case study because it describes local infrastructure, documentation and Git workflow decisions without including private customer material, production credentials or real operational data.

It should not be treated as evidence of a production deployment.

Correct framing:

Local development and documentation case study for WordPress plugin validation, Docker Compose hygiene and safe Git recovery.

Incorrect framing:

Production WordPress deployment
Enterprise IAM platform
Customer evidence archive
Kubernetes or cloud platform implementation

Final status

Status: complete
Repository state: clean
Branch: main
Docker environment: documented and validated
Healthcheck: improved
Old branches: removed
Stale remote references: pruned
Further action required: none