Skip to content
InsightSpaceInsightSpace

Local development

The normal developer workflow runs PostgreSQL in Docker and runs the backend and frontend directly on the host. Run the extractor and local inference only when the work requires document indexing or local models.

Prerequisites

Section titled “Prerequisites”
  • Docker with Compose
  • .NET 10 SDK
  • Node.js and pnpm compatible with the frontend lockfile
  • uv for extractor development
  • Ollama or access to an allowed remote model provider when research is required

Prepare configuration

Section titled “Prepare configuration”

From the InsightSpace application repository:

Terminal window
cp .env.template .env

Review the template and provide the required ignored files under secrets/. Secret values belong in files, not in .env or appsettings.json. Ask a maintainer for license or provider credentials; do not invent fallback values.

Start PostgreSQL

Section titled “Start PostgreSQL”
Terminal window
docker compose up -d database

The development override publishes PostgreSQL on 127.0.0.1:5432. Do not start the frontend or backend as Docker services for the normal host-based development loop.

Apply database migrations

Section titled “Apply database migrations”

The backend checks for pending migrations and refuses normal startup when it finds any. Apply them deliberately:

Terminal window
dotnet run \
  --project backend/src/InsightSpace.Backend/InsightSpace.Backend.csproj \
  -- --migrate

Start the backend

Section titled “Start the backend”
Terminal window
dotnet run --project backend/src/InsightSpace.Backend/InsightSpace.Backend.csproj

Development settings serve the API on the local backend port and allow the frontend development origins.

Start the frontend

Section titled “Start the frontend”

In another terminal:

Terminal window
cd frontend
pnpm install
pnpm dev

The frontend development server listens on port 8080. On a new database, follow the bootstrap administrator flow shown by the application.

Run the extractor when needed

Section titled “Run the extractor when needed”

The extractor is required for uploads and indexing. Run it directly with uv:

Terminal window
cd extractor
uv sync
EXTRACTOR_TOKEN_FILE=../secrets/extractor_token \
EXTRACTOR_SCRATCH_DIR=/tmp/insightspace-extractor \
  uv run uvicorn app.main:app --reload --port 8000

The extractor uses CPU by default and can use Apple Metal when run natively on compatible macOS hardware. A Linux container cannot use Apple Metal.

Local inference

Section titled “Local inference”

Development settings can point at Ollama on http://localhost:11434. Make sure the configured embedding and reranking models are available before indexing. Remote providers are enabled only when their token file and required provider settings are configured.

Stop local infrastructure

Section titled “Stop local infrastructure”
Terminal window
docker compose stop database

This stops PostgreSQL without deleting its persistent volume.