Gravity — Development notes

Quick instructions for running the app in development with a live-reloading frontend.

Podman (recommended):

podman compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml up -d

Docker (replace podman with docker):

docker compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml up -d

This starts the backend and a containerized Vite dev server for the frontend (HMR). The dev frontend is reachable on host port 5173 by default.

To stop the dev stack:

podman compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml down

To populate the database with realistic sample data (user, workspace, projects, tickets, comments, etc.), run the following command from the server directory:

cd server
npm run db:seed

This script is idempotent. It refreshes the default test@example.com / password123 seed user and deletes specifically named seed objects (for example, the seed-* workspaces, projects, and tickets) before inserting fresh data, so it can be safely run multiple times without causing duplicates or destroying other user data.

Documentation is located in the docs/ folder. Good starting points:

• docs/CSRF_IMPLEMENTATION.md for server CSRF details
• docs/mcp/MCP_FLOW.md for MCP request handling and realtime mutation events
• docs/mcp/ADDING_MCP_SSE_EVENTS.md for adding new SSE-emitting MCP tools
• docs/client/CLIENT_STATE_MANAGEMENT.md for client-side cache and SSE handling
• docs/server/SERVER_ARCHITECTURE_OVERVIEW.md for the backend module layout

If you want to keep the production-style frontend container on host port 5173 up to date without manually rerunning up --build, use the Docker watch override:

docker compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml up -d
docker compose -f docker/docker-compose.yml -f docker/docker-compose.dev.yml watch

Run watch in a second terminal and leave it attached. It rebuilds the backend and frontend images whenever files under server/, client/, or library/ change (excluding ignored paths like node_modules/, build output, and tests).

Prerequisites & notes:

• Requires Docker Compose CLI v2.22 or newer (the Compose "watch" feature).
• The watch config syncs source files into running development image targets (server -> /app/server/src, client -> /app/client/src) and issues rebuilds when package files change. Ensure node_modules is excluded from watched paths for performance.

If you prefer running only the frontend dev server in a container (maps host node_modules and preserves UID):

cd "$(pwd)"
podman rm -f gravity_frontend_dev_run || true
podman run -d --rm --userns=keep-id --name gravity_frontend_dev_run \
  -p 5173:5173 \
  -v "$(pwd)/client":/app/client:Z \
  -v "$(pwd)/library":/app/library:Z \
  -v "$(pwd)/server":/app/server:Z \
  -v "$(pwd)/client/node_modules":/app/client/node_modules:Z \
  -w /app/client node:20-slim \
  sh -c "npm run dev -- --host 0.0.0.0 --port 5173"

Notes:

• The server source mount provides the shared HTML-sanitization policy and rich-text schema used by the frontend build.
• Frontend Dockerfile lives at client/Dockerfile, and the API container Dockerfile lives at server/Dockerfile. -- If you want that nginx container on 5173 to rebuild automatically on frontend changes, use docker/docker-compose.dev.yml with docker compose watch.
• If you change frontend source and want the production nginx container to serve changes, rebuild the image with:

podman compose -f docker/docker-compose.yml up -d --build frontend

• On some systems you may need to adapt the volume flags (:Z, :z) or file ownership to allow the container to read mounted files.

Run the repo's local CI flow from the project root with:

./local-ci.sh

This delegates to the maintained CI driver in scripts/local-ci.sh, which installs dependencies, runs the client and server test suites, builds both apps, and performs a compose-based smoke check.

Before deployment, run npm --workspace=server run check-env and follow deployment configuration for required secrets, production OAuth/origin settings, signed webhooks, and dependency readiness.