Robert Perez
123 lines
2.7 KiB
Markdown
123 lines
2.7 KiB
Markdown
# 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
|
|
```
|