Environment & Local Deployment

Dependencies

Dependency	Version	Purpose	Required
Go	1.26+	server	yes
Node.js	18+	converter (npm install once, no daemon)	yes
Python + uv	3.10+	edit-service	for editing/diff; browsing works without it
PostgreSQL	14+	issues/changes/overrides persistence	optional (file storage by default)

Python dependencies: edit-service depends on ifcopenshell / ifcdiff / ifcquery (all official PyPI releases, aligned with IfcOpenShell 0.8.5); uv sync installs them directly. No local IfcOpenShell source checkout needed.

Docker Compose (recommended)

Docker only; one command starts the full stack (web / server / converter / edit-service):

cp .env.example .env   # optional: every entry has a default
docker compose up --build

Open http://localhost:8080. Data lives in a named volume (aiifc-data); models survive down/up.

With PostgreSQL (issues/changes/overrides via PG, tables created automatically):

# set in .env: VIEWER_PG_DSN=postgres://aiifc:aiifc@postgres:5432/aiifc?sslmode=disable
docker compose --profile pg up -d

Tunables (ports, DATA_DIR, VIEWER_PG_DSN, …) are listed in .env.example.

Start (four terminals, no Docker)

# 0. One-time dependency install
cd viewer/converter && npm install
cd ../web && npm install
cd ../edit-service && uv sync

# 1. edit-service (:8100) — VIEWER_DATA_DIR must point to the absolute path of viewer/data
cd viewer/edit-service
VIEWER_DATA_DIR="$(cd ../data && pwd)" uv run uvicorn app.main:app --port 8100

# 2. Go server (:8090)
cd viewer/server && go run ./cmd/server

# 3. web (:5173)
cd viewer/web && npm run dev

Open http://localhost:5173 and you are ready. Full configuration: Configuration.

Verification

# End-to-end smoke (server must be running; the edit-flow section skips when edit-service is unreachable)
cd viewer && ./scripts/smoke.sh

# Per-layer tests
cd viewer/server && go test ./...
cd viewer/edit-service && uv run --group dev pytest
cd viewer/web && npm test
cd viewer/converter && npm test

Note: upload, conversion and review do not need edit-service or PostgreSQL; editing, versions and diff do.