[Spec Kit] Initial commit — constitution, spec, plan, and tasks for Reaction Image Board v1

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

@@ -0,0 +1,144 @@
+# 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
+
+```bash
+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
+
+```bash
+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
+
+```bash
+curl http://localhost:8000/api/v1/health
+# → {"status":"ok"}
+```
+
+### 4. Open the UI
+
+Navigate to [http://localhost:4200](http://localhost:4200) in your browser.
+The empty library is displayed.
+
+---
+
+## Upload a test image (API)
+
+```bash
+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](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):
+```bash
+docker compose run --rm api pytest
+```
+
+**UI tests**:
+```bash
+docker compose run --rm ui ng test --watch=false
+```
+
+**Linters**:
+```bash
+docker compose run --rm api ruff check .
+docker compose run --rm ui npm run lint
+```
+
+---
+
+## Stopping and resetting
+
+```bash
+# 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.