docs: fix DX for new contributors

- Fix port mismatch: Dockerfile EXPOSE 8000, .env.example PORT=8000,
  compose.yml gets explicit PORT=8000
- Add thoughts-frontend/.env.example with all required vars
- Document NEXT_PUBLIC_FEDIVERSE_DOMAIN in README
- Document private cargo registry (k-ap on Gitea)
- Add local dev workflow: make dev-infra → cargo run → bun dev
- Split make targets: test-unit (no DB), test-integration, up

.env.example

@@ -9,7 +9,7 @@ BASE_URL=http://localhost:3000
 
 # Optional
 HOST=0.0.0.0
-PORT=3000
+PORT=8000
 
 # CORS — comma-separated allowed origins, or * for permissive (default: *)
 CORS_ORIGINS=*

Dockerfile

@@ -52,7 +52,7 @@ WORKDIR /app
 COPY --from=builder /build/target/release/thoughts        ./thoughts
 COPY --from=builder /build/target/release/thoughts-worker ./thoughts-worker
 
-EXPOSE 3000
+EXPOSE 8000
 
 ENV RUST_LOG=info
 

Makefile

@@ -16,13 +16,33 @@ fmt-check:
 clippy:
 	cargo clippy -- -D warnings
 
-# Run the test suite.
+# Run the full test suite (requires DATABASE_URL).
 test:
 	cargo test
 
+# Unit tests only — no database required.
+test-unit:
+	cargo test -p domain -p application -p api-types -p activitypub
+
+# Integration tests only — requires DATABASE_URL.
+test-integration:
+	cargo test -p postgres -p postgres-federation -p postgres-search -p presentation
+
 # Apply fmt + clippy auto-fixes in one shot.
 fix:
 	cargo fmt
 	cargo clippy --fix --allow-dirty --allow-staged
 
-.PHONY: check fmt fmt-check clippy test fix
+# Start infra (Postgres + NATS) for local development.
+dev-infra:
+	docker compose up postgres nats -d
+
+# Stop infra.
+dev-infra-down:
+	docker compose down
+
+# Full Docker stack.
+up:
+	docker compose up --build
+
+.PHONY: check fmt fmt-check clippy test test-unit test-integration fix dev-infra dev-infra-down up

README.md

@@ -85,6 +85,11 @@ Users can upload avatar and banner images via `PUT /users/me/avatar` and `PUT /u
 - Rust stable (1.80+)
 - PostgreSQL 15+
 - NATS with JetStream (optional — see [Without NATS](#without-nats))
+- Docker & Docker Compose (for the easiest local setup)
+
+### Private cargo registry
+
+The `k-ap` crate (ActivityPub protocol library) is hosted on a private Gitea registry configured in `.cargo/config.toml`. To build the project you need read access to `git.gabrielkaszewski.dev`. If you're contributing and don't have access, open an issue and I'll sort it out.
 
 ## Environment Variables
 
@@ -121,8 +126,42 @@ Copy `.env.example` to `.env` and fill in your values.
 | `UPLOAD_MAX_BYTES` | `5242880` | Max upload size in bytes (default 5 MiB) |
 | `UPLOAD_ALLOWED_TYPES` | `image/jpeg,image/png,image/gif,image/webp,image/avif` | Comma-separated allowed MIME types |
 
+### Frontend environment
+
+Copy `thoughts-frontend/.env.example` to `thoughts-frontend/.env.local` and adjust:
+
+| Variable | Description |
+|---|---|
+| `NEXT_PUBLIC_API_URL` | API URL for client-side (browser) requests, e.g. `http://localhost:8000` |
+| `NEXT_PUBLIC_SERVER_SIDE_API_URL` | API URL for SSR requests — same as above locally, or `http://api:8000` inside Docker |
+| `NEXT_PUBLIC_FEDIVERSE_DOMAIN` | (Optional) Domain shown on profile fediverse handles, e.g. `yourinstance.example.com` |
+
 ## Run
 
+### Local development (recommended)
+
+Start only the infrastructure containers (Postgres + NATS), then run the Rust backend and Next.js frontend natively for fast iteration:
+
+```bash
+# 1. Start Postgres + NATS
+make dev-infra
+
+# 2. Copy and fill in env files
+cp .env.example .env
+cp thoughts-frontend/.env.example thoughts-frontend/.env.local
+
+# 3. API server (runs migrations automatically on startup)
+cargo run -p bootstrap
+
+# 4. Event worker (separate terminal, optional)
+cargo run -p worker
+
+# 5. Frontend (separate terminal)
+cd thoughts-frontend && bun install && bun dev
+```
+
+### Bare metal
+
 ```bash
 # API server (runs migrations automatically on startup)
 cargo run -p bootstrap
@@ -136,14 +175,20 @@ Both processes share the same PostgreSQL database. The worker is optional but re
 ## Test
 
 ```bash
-# Unit tests — no database required
-cargo test -p application
+# Unit tests only — no database required
+make test-unit
 
-# Full workspace (requires DATABASE_URL pointing to a running PostgreSQL)
-cargo test --workspace
+# Integration tests — requires DATABASE_URL pointing to a running PostgreSQL
+make test-integration
+
+# Everything (unit + integration)
+make test
+
+# Full check suite: fmt + clippy + tests
+make check
 ```
 
-The `application` crate contains unit tests for all event services and use cases backed by in-memory fakes from `domain`'s `test-helpers` feature. These are the fastest feedback loop for business logic.
+`make test-unit` runs domain, application, api-types, and activitypub tests using in-memory fakes — the fastest feedback loop for business logic. `make test-integration` runs the adapter crates against a live PostgreSQL.
 
 ## API
 
@@ -203,12 +248,12 @@ docker build -t thoughts-frontend \
 docker run -p 3000:3000 thoughts-frontend
 ```
 
-### Local development stack
+### Full Docker stack
 
 `compose.yml` spins up the full stack: PostgreSQL, NATS (with JetStream and monitoring on port 8222), the API server, the event worker, and the frontend.
 
 ```bash
-docker compose up
+make up          # or: docker compose up --build
 ```
 
 Services:

compose.yml

@@ -30,6 +30,7 @@ services:
       DATABASE_URL: postgres://postgres:postgres@postgres:5432/thoughts
       JWT_SECRET: change-me-in-production
       BASE_URL: http://localhost:8000
+      PORT: 8000
       NATS_URL: nats://nats:4222
       RUST_LOG: info
       STORAGE_BACKEND: local

thoughts-frontend/.env.example

@@ -0,0 +1,6 @@
+# API endpoints
+NEXT_PUBLIC_API_URL=http://localhost:8000              # client-side (browser) requests
+NEXT_PUBLIC_SERVER_SIDE_API_URL=http://localhost:8000   # SSR requests (use http://api:8000 inside Docker)
+
+# Fediverse handle display (optional)
+# NEXT_PUBLIC_FEDIVERSE_DOMAIN=yourinstance.example.com

thoughts-frontend/.gitignore

@@ -32,6 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env.example
 
 # vercel
 .vercel