GKaszewski/thoughts
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

Update wiki page 'Development-Setup'

Gabriel Kaszewski
2026-05-15 15:05:20 +00:00
parent 50e7260816
commit ef3fae91bf
1 changed files with 64 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
Development-Setup.md

@@ -2,50 +2,52 @@
## Prerequisites ## Prerequisites
| Tool | Purpose | | Tool | Version | Purpose |
|---|---| |---|---|---|
| Rust (stable) | Backend | | Rust | stable 1.80+ | Backend |
| Node.js + Bun | Frontend | | Node.js + Bun | latest | Frontend |
| PostgreSQL | Database | | PostgreSQL | 15+ | Database |
| Docker + Docker Compose | Optional: run deps in containers | | NATS | optional | Event transport (federation + notifications) |
| Docker + Docker Compose | optional | Run deps in containers |
## Backend ## Backend
```bash ```bash
cd thoughts-backend
# Copy and fill in env # Copy and fill in env
cp .env.example .env cp .env.example .env
# Run migrations # Start the API server (runs migrations automatically on startup)
cargo run -p migration cargo run -p bootstrap
# Start the backend (tokio runtime) # In a second terminal: start the event worker (optional)
cargo run -p thoughts-backend cargo run -p worker
``` ```
The backend starts on `http://localhost:3001` by default. The API server starts on `http://localhost:8000`.
Both processes read from the same `.env` file.
### Environment Variables (`thoughts-backend/.env.example`) ### Environment Variables (`.env.example`)
```env
DATABASE_URL=postgres://postgres:password@localhost:5432/thoughts
JWT_SECRET=change-me
BASE_URL=http://localhost:8000
NATS_URL=nats://localhost:4222 # optional
``` ```
DATABASE_URL=postgres://user:pass@localhost:5432/thoughts
JWT_SECRET=your-secret-here `BASE_URL` is used to construct ActivityPub actor URLs and AP object IDs — must be the publicly reachable URL in production.
```
### Running Tests ### Running Tests
```bash ```bash
cd thoughts-backend # Unit tests — no database required
cargo test -p application
# All tests (requires running PostgreSQL) # Full workspace (requires DATABASE_URL pointing to a running PostgreSQL)
cargo test cargo test --workspace
# API integration tests only
cargo test -p thoughts-backend --test api
``` ```
Tests spin up a test database; set `TEST_DATABASE_URL` in `.env` if it differs from `DATABASE_URL`. The `application` crate uses in-memory fakes from `domain`'s `test-helpers` feature for fast, isolated unit tests of all business logic.
--- ---
@@ -54,39 +56,36 @@ Tests spin up a test database; set `TEST_DATABASE_URL` in `.env` if it differs f
```bash ```bash
cd thoughts-frontend cd thoughts-frontend
# Copy and fill in env
cp .env.example .env.local
# Install dependencies # Install dependencies
bun install bun install
# Start dev server # Start dev server
bun dev bun run dev # http://localhost:3000
``` ```
The frontend starts on `http://localhost:3000` and proxies `/api/*` to the backend.
### Environment Variables (`thoughts-frontend/.env.example`) ### Environment Variables (`thoughts-frontend/.env.example`)
``` ```env
NEXT_PUBLIC_API_URL=http://localhost:3001 NEXT_PUBLIC_API_URL=http://localhost:8000 # client-side requests
NEXT_PUBLIC_SERVER_SIDE_API_URL=http://localhost:8000 # SSR requests
``` ```
--- ---
## Running Everything with Docker Compose ## Running Everything with Docker Compose
For a fully isolated local environment:
```bash ```bash
# Start all services (backend, frontend, postgres, nginx) # Start all services (api, worker, frontend, postgres, nats, nginx)
docker compose up docker compose up
# Or just the database and let services run natively # Or just the database
docker compose up database docker compose up database
# Or database + NATS only
docker compose up database nats
``` ```
The `compose.yml` at the repo root defines all services for local development. `compose.yml` at the repo root defines all services for local development.
--- ---
@@ -94,20 +93,32 @@ The `compose.yml` at the repo root defines all services for local development.
``` ```
thoughts/ thoughts/
├── compose.yml # Dev Docker Compose ├── Cargo.toml # Workspace root
├── compose.prod.yml # Production Docker Compose ├── .env.example # Backend env template
├── nginx/ # Nginx config ├── compose.yml # Dev Docker Compose
├── thoughts-backend/ # Rust backend (workspace) ├── compose.prod.yml # Production Docker Compose
│ ├── api/ # HTTP layer ├── Dockerfile # Multi-stage build (api + worker binaries)
│ ├── app/ # Business logic ├── nginx/
│ ├── models/ # Domain types ├── crates/
│ ├── common/ # Shared utilities │ ├── domain/ # Pure domain types & port traits
│ ├── doc/ # OpenAPI generation │ ├── application/ # Use cases (business logic)
│ ├── migration/ # DB migrations │ ├── api-types/ # REST request/response DTOs
│ └── utils/ # Test helpers │ ├── presentation/ # Axum HTTP router, OpenAPI
└── thoughts-frontend/ # Next.js frontend │ ├── bootstrap/ # API server binary
├── app/ # App Router pages │ ├── worker/ # Event worker binary
├── components/ # React components │ └── adapters/
├── hooks/ # Custom hooks │ ├── auth/
└── lib/ # API client, utils │ ├── postgres/ # SQL repos + migrations/
│ ├── postgres-search/
│ ├── postgres-federation/
│ ├── activitypub-base/
│ ├── activitypub/
│ ├── nats/
│ ├── event-payload/
│ └── event-transport/
└── thoughts-frontend/ # Next.js frontend
├── app/ # App Router pages
├── components/ # React components (incl. federation/)
├── hooks/
└── lib/ # API client, utils
``` ```