reactbin/specs/001-reaction-image-board/quickstart.md

Quickstart: Reaction Image Board v1

Goal: Get a fully functional local development environment running in under 5 minutes from a clean checkout.

---

Prerequisites

• Docker and Docker Compose v2 installed
• Git

No other tools (Python, Node, etc.) are required on the host — everything runs inside containers.

---

Steps

1. Clone and configure

git clone <repo-url> reactbin
cd reactbin
cp .env.example .env

The .env.example file contains safe defaults for local development. You do not need to edit .env to get started.

2. Start all services

docker compose up

This starts four services:

• postgres — PostgreSQL on port 5432
• minio — S3-compatible object storage on port 9000 (console on 9001)
• api — FastAPI application on port 8000
• ui — Angular dev server on port 4200

On first run, Docker builds the API and UI images (a few minutes). Subsequent starts are fast.

3. Verify the API

curl http://localhost:8000/api/v1/health
# → {"status":"ok"}

4. Open the UI

Navigate to http://localhost:4200 in your browser. The empty library is displayed.

---

Upload a test image (API)

curl -X POST http://localhost:8000/api/v1/images \
  -F "file=@/path/to/image.jpg" \
  -F "tags=test,sample"

Expected response: HTTP 201 with the image JSON including its UUID.

---

Upload a test image (UI)

1. Click the Upload button in the library view
2. Drag and drop an image (JPEG, PNG, GIF, or WebP, max 50 MB)
3. Type some tags separated by commas
4. Click Upload
5. You are redirected to the image's detail page

---

MinIO Console

The MinIO management console is accessible at http://localhost:9001.

Default credentials (from .env.example):

• User: minioadmin
• Password: minioadmin

You can inspect uploaded objects in the bucket here.

---

Running tests

API tests (inside the container):

docker compose run --rm api pytest

UI tests:

docker compose run --rm ui ng test --watch=false

Linters:

docker compose run --rm api ruff check .
docker compose run --rm ui npm run lint

---

Stopping and resetting

# Stop all services (preserves data)
docker compose down

# Stop and remove all data (PostgreSQL + MinIO volumes)
docker compose down -v

---

Environment variables

All configuration comes from .env. The table below shows every variable and its default:

Variable	Default	Notes
DATABASE_URL	postgresql+asyncpg://reactbin:reactbin@postgres:5432/reactbin	Async DSN for SQLAlchemy
S3_ENDPOINT_URL	http://minio:9000	MinIO endpoint inside Docker network
S3_BUCKET_NAME	reactbin	Created automatically on first API start
S3_ACCESS_KEY_ID	minioadmin	MinIO root user
S3_SECRET_ACCESS_KEY	minioadmin	MinIO root password
S3_REGION	us-east-1	Required even for MinIO
API_BASE_URL	http://localhost:8000	Injected into Angular at build time
MAX_UPLOAD_BYTES	52428800	50 MiB

For production, replace MinIO credentials and DATABASE_URL with real values. Never commit a .env file with real credentials.