Getting Started¶

Set up Prolexio for local development. Estimated time: 5 minutes.

Prerequisites¶

Tool	Version	Installation
Rust	>= 1.75	rustup.rs
Node.js	>= 20 (or Bun >= 1.0)	nodejs.org
PostgreSQL	>= 15	`brew install postgresql@15` or Docker
Docker	Latest	For Gotenberg PDF conversion
Git	Latest

Step 1: Clone the Repository¶

git clone <repo-url>
cd prolexio

Step 2: Database Setup¶

Create the PostgreSQL database:

createdb prolexio

Or using Docker:

docker run -d --name prolexio-db \
  -e POSTGRES_DB=prolexio \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:15

Step 3: Server Setup¶

cd server
cp .env.example .env

Edit .env and configure DATABASE_URL:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/prolexio

Run database migrations, then build:

sqlx migrate run
cargo build

Why migrations first?

sqlx verifies SQL queries at compile time against the live database. Without migrations applied, cargo build will fail.

Expected output

Applied 1/migrate initial schema (XXms)
Applied 2/migrate ...
...
Applied 139/migrate office_rib (XXms)

Step 4: Seed Demo Data¶

Populate the database with fictional demo data (100% fictional — RGPD compliant):

cargo run --bin seed-demo

Expected output

Seeding demo data...
Demo seed complete!

This creates:

2 offices (Étude Durand & Associés, SCP Martin-Petit)
5 users (admin, 2 commissaires, 2 clercs) — password: Demo2026!
12 participants (individuals, companies, court)
8 cases in various statuses with claims, titles, deeds, events

Admin login: admin@prolexio.demo / Demo2026!

Step 5: Start the Server¶

cargo run

Expected output

listening on 0.0.0.0:3001

Step 6: Client Setup¶

In a new terminal:

cd client
npm install    # or: bun install
npm run dev    # or: bun dev

Expected output

VITE v5.x.x ready in XXms
➜ Local: http://localhost:1420/

Open http://localhost:1420 in your browser.

Step 7: Gotenberg (Optional)¶

Gotenberg is required for PDF export (DOCX → PDF conversion):

docker run --rm -p 3000:3000 gotenberg/gotenberg:8

Configure the Gotenberg URL in server/.env:

GOTENBERG_URL=http://localhost:3000

Verify Installation¶

Run these checks to confirm everything works:

Check	Command	Expected
Server compiles	`cd server && cargo build`	0 errors, 0 warnings
Migrations applied	`sqlx migrate info`	All migrations applied
Demo seed loaded	`cargo run --bin seed-demo`	"Demo data already exists — skipping"
Server starts	`cargo run`	"listening on 0.0.0.0:3001"
Client starts	`cd client && npm run dev`	Vite ready on localhost:1420
Login works	Open browser, login with `admin@prolexio.demo` / `Demo2026!`	Dashboard with demo data

Developer Documentation¶

To run this documentation site locally:

cd docs
python3 -m venv dev/.venv
source dev/.venv/bin/activate
pip install -r requirements.txt
mkdocs serve

Open http://localhost:8000 in your browser.

Note

Run mkdocs serve from the docs/ directory (where mkdocs.yml lives), not from docs/dev/.

Documentation Deployment¶

Developer documentation is automatically deployed to Cloudflare Pages when changes are pushed to main that modify files in:

docs/dev/** (Markdown source files)
docs/mkdocs.yml (MkDocs configuration)
docs/requirements.txt (Python dependencies)

The CI workflow (.github/workflows/docs-dev.yml) runs mkdocs build --strict and deploys via cloudflare/wrangler-action@v3. Strict mode ensures broken links and invalid references fail the build before deployment.

Cloudflare Pages Setup

Requires two repository secrets: CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Create the project prolexio-dev-docs in the Cloudflare dashboard (Pages → Create a project → Direct upload). The site URL will be prolexio-dev-docs.pages.dev (custom domain configurable).

Automated Screenshots¶

Capture documentation screenshots from the running application (with demo seed loaded):

cd docs/screenshots
npm install
npx playwright install chromium

With the server and client running (Steps 5–6), capture all screenshots:

npm run capture

Screenshots are saved to docs/user/screenshots/ as PNG files (1280×800 viewport). They overwrite existing files on each run, so git diff shows which screens changed.

Prerequisites

The server (cargo run on port 3001) and client (npm run dev on port 1420) must be running with demo seed loaded before capturing screenshots.

Common Issues¶

Port 3001 already in use¶

Another instance of the server is running. Kill it:

lsof -ti:3001 | xargs kill

DATABASE_URL not set¶

Ensure .env file exists in server/ with a valid DATABASE_URL. Copy from .env.example:

cd server && cp .env.example .env

sqlx migrate run fails¶

Make sure the PostgreSQL database exists and is accessible:

psql -d prolexio -c "SELECT 1"

If using Docker, ensure the container is running: docker ps.

Gotenberg connection refused¶

Start Gotenberg with Docker (see Step 7 above). PDF export will fail gracefully without Gotenberg — the rest of the application works fine.

Node.js version too old¶

Prolexio requires Node.js >= 20. Check your version:

node --version

Upgrade via nvm install 20 or brew install node@20.