petmaster/README.md

# Petmaster Dev Sandbox

Docker-based development environment for the petmaster project.

## Quick Start

```bash
# 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:

```bash
sudo -g docker docker <command>
```

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

## Managing the Sandbox

### Start the stack
```bash
sudo -g docker docker compose up -d
```

### Stop the stack
```bash
sudo -g docker docker compose down
```

### Stop and clean volumes
```bash
sudo -g docker docker compose down -v
```

### View logs
```bash
sudo -g docker docker compose logs -f
```

### Run commands in containers
```bash
# 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
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:
```bash
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
```bash
sudo -g docker docker compose down -v --remove-orphans
sudo -g docker docker compose up -d
```