Skip to content

README.md

Latest commit

 

History

History
103 lines (75 loc) · 5.05 KB

README.md

File metadata and controls

103 lines (75 loc) · 5.05 KB

Second Brain Developer Environment

This monorepo hosts the FastAPI backend (apps/api) and the Vite-powered React frontend (apps/web). You can still run each workspace directly with uv or npm, but a Docker Compose stack now provides a single command that boots both services plus PostgreSQL with the same settings used by the native scripts.

Prerequisites

  • Docker Engine 24+ (Docker Desktop works on macOS/Windows) with the Compose v2 plugin.
  • 8 GB RAM available for containers (API + web + Postgres barely use ~1 GB but leave headroom for tooling).
  • Optional: Python 3.12 + uv and Node 18+ if you prefer to run the workspaces outside Docker (see apps/api/README.md and apps/web/README.md).

Run Everything With Docker Compose

# Build images (picks up the Dockerfiles in apps/api and apps/web) and start the stack
docker compose up --build

Compose mounts the repo into each container for live reload (FastAPI auto-reload + Vite HMR) and keeps dependency caches in named volumes:

Volume Mount Purpose
api-venv /workspace/apps/api/.venv Reuses uv sync installs
api-uv-cache /root/.cache/uv Keeps wheel/cache data
web-node-modules /workspace/apps/web/node_modules Keeps npm installs outside the bind mount
postgres-data /var/lib/postgresql/data Persists database state

Environment files and overrides

  • .env.compose (checked in) stores the defaults for database credentials, API CORS settings, and front-end env vars that containers need.
  • Optional .env.compose.local (ignored) lets you change container-level settings. Copy the default file, tweak values, then point Compose at it by exporting COMPOSE_ENV_FILE=.env.compose.local or writing the variable into your root .env.
  • Optional root .env (ignored) feeds host-level overrides such as custom API_PORT, WEB_PORT, or a different COMPOSE_ENV_FILE. Example:
echo "API_PORT=9000" >> .env
echo "COMPOSE_ENV_FILE=.env.compose.local" >> .env
docker compose up --build

Without any overrides the services bind to http://localhost:8000 (API), http://localhost:5173 (web), and localhost:5432 (Postgres).

Expected output (docker compose up)

postgres-1  | PostgreSQL init process complete; ready for start up.
postgres-1  | database system is ready to accept connections
api-1       | ✔ Synced virtual environment using uv.lock
api-1       | INFO:     Will watch for changes in these directories: ['/workspace/apps/api']
api-1       | INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
web-1       | VITE v7.1.7  ready in 1506 ms
web-1       | ➜  Local:   http://0.0.0.0:5173/
web-1       | ➜  Network: http://127.0.0.1:5173/
web-1       | ready in 30 ms. Waiting for file changes...

Save files under apps/api or apps/web and the containers will reload automatically without rebuilding images.

Helpful commands

Purpose Command
Apply DB migrations docker compose exec api uv run alembic upgrade head
Generate a migration docker compose exec api uv run alembic revision --autogenerate -m "add table"
Run backend tests docker compose exec api uv run pytest
Run frontend tests docker compose exec web npm run test
Inspect Postgres docker compose exec postgres psql -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-second_brain}
Tail logs docker compose logs -f api (or web, postgres)
Stop stack docker compose down
Reset volumes/data docker compose down -v

Database bootstrapping

The API container reads the same DATABASE_* variables as Alembic, so migrations work exactly like the native workflow. After the stack is up, run:

docker compose exec api uv run alembic upgrade head

Sample output:

api-1  | INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
api-1  | INFO  [alembic.runtime.migration] Running upgrade  -> 1f6b95cf29d9, create bookmark tables

Use docker compose exec postgres psql -U postgres -d second_brain -c '\dt' to confirm tables or inspect data.

Native scripts still work

If you would rather run the workspaces directly:

cd apps/api && uv sync && uv run uvicorn app.main:app --reload
cd apps/web && npm install && npm run dev

Those commands match the ones used inside the Compose stack, so instructions in the per-app READMEs remain accurate.

Troubleshooting

  • Environment edits not taking effect – double-check whether the value lives in .env (host-level override) or .env.compose (container-level). Remember to restart the stack after editing.
  • Dependency issues – wipe the cache volumes (docker compose down -v api-venv api-uv-cache web-node-modules) or run docker compose down -v to rebuild everything.
  • Port already in use – override API_PORT/WEB_PORT/POSTGRES_PORT in your root .env and restart the stack.
  • Need a shell inside a service – docker compose exec api bash (or web, postgres) drops you into the container so you can run uv, npm, or psql commands interactively.