petmaster/README.md

Petmaster Dev Sandbox

Docker-based development environment for the petmaster project.

Quick Start

# Start the dev stack
bash start-sandbox.sh

# Or manually:
sudo -g docker docker compose up -d

Architecture

The sandbox provides four services:

Service	Image	Port	Purpose
PostgreSQL 16	postgres:16-alpine	5432	Development database
Redis 7	redis:7-alpine	6379	Caching / session store
Node.js 22 (Dev)	node:22-alpine	9229	Backend dev environment
Node.js 22 (React)	node:22-alpine	3000	Frontend dev server

Configuration

Database Connection

PostgreSQL: postgresql://postgres:postgres@localhost:5432/petmaster_dev
Redis:      redis://localhost:6379

Docker Auth

Because our container doesn't own /run/docker.sock, all Docker commands must run with:

sudo -g docker docker <command>

The start-sandbox.sh script wraps this for convenience.

Managing the Sandbox

Start the stack

sudo -g docker docker compose up -d

Stop the stack

sudo -g docker docker compose down

Stop and clean volumes

sudo -g docker docker compose down -v

View logs

sudo -g docker docker compose logs -f

Run commands in containers

# Shell in the Node dev container
sudo -g docker docker exec -it petmaster-node-dev sh

# Shell in PostgreSQL
sudo -g docker docker exec -it petmaster-postgres psql -U postgres

# Redis CLI
sudo -g docker docker exec -it petmaster-redis redis-cli

Frontend hot reload

The override config maps ./frontend/src into the React container. Files on the host are visible at /app/src inside the container. For full hot-reload, replace the placeholder container command with your actual dev server start command.

Health Checks

Run the included healthcheck script to validate everything:

bash healthcheck.sh

This checks:

• Container status (all running)
• PostgreSQL connectivity and query execution
• Redis PING/PONG
• Port reachability for all services

Volume Data

Persistent data is stored in Docker volumes:

• petmaster_postgres-data — PostgreSQL data
• petmaster_redis-data — Redis data

Node.js containers use ephemeral bind mounts (./node-data) for temporary files.

Troubleshooting

Permission denied on docker.sock

Ensure you're using sudo -g docker prefix:

sudo -g docker docker ps

Port conflicts

If ports 5432, 6379, or 3000 are already in use, modify the port mappings in docker-compose.yml.

Stale containers

sudo -g docker docker compose down -v --remove-orphans
sudo -g docker docker compose up -d