This guide covers setting up and running PKI Manager for local development.

• Node.js >= 20.0.0
• pnpm >= 9.0.0
• Docker (for Cosmian KMS and Keycloak)

# 1. Start infrastructure containers
cd kms && docker compose up -d          # Cosmian KMS  :42998
cd keycloak && docker compose up -d     # Keycloak     :42997 (optional, OIDC)

# 2. Install dependencies
pnpm install

# 3. Configure environment
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

# 4. Run database migrations
cd backend && pnpm db:migrate

# 5. Start development servers (from root)
pnpm dev

The committed dev config targets *.ymbihq.local on the 42xxx/52xxx range (backend/.env, frontend/.env, frontend/vite.config.ts) — not the 3000/5173 defaults.

pnpm dev at the root runs scripts/dev-session.sh, which keeps mprocs (see mprocs.yaml — three panes: backend, frontend, backlog) inside a tmux session named dev-pki-manager.

Why the wrapper. The terminal pane is not the owner of the stack: Orca restarts its panes on every app update, the pane dies, and mprocs keeps running detached. A bare mprocs relaunch then starts a second stack whose Vite hops to another port, and you end up debugging the wrong server. pnpm dev is idempotent, so after an Orca update you just run it again and land back in the same stack.

It never matches processes by name — other projects run their own mprocs. It keys off this repo's session name, and off the cwd of whoever holds our ports: an intruder from another path aborts the launch, an orphan from this repo is offered for cleanup (--force to skip the prompt).

mprocs needs a TTY, but the wrapper creates the session detached and only attaches when it has one — so an agent can pnpm dev headlessly without Stdin is not a tty, then read the stack with tmux capture-pane -p -t dev-pki-manager.

Launch it in its own visible Orca terminal tab:

orca terminal create \
  --worktree path:/home/oriol/miimetiq3/pki-manager \
  --title "DEV STACK" --command "pnpm dev" --json
# → returns a handle: term_<uuid>

orca terminal read --terminal term_<uuid>   # read pane state / logs without a TTY
orca terminal switch --terminal term_<uuid> # bring the tab to the foreground

After an Orca update leaves you at a bare shell, do not relaunch blindly — just run pnpm dev (or tmux attach -t dev-pki-manager) and you are back in the running stack.

To really stop it use pnpm dev:stop; orca terminal stop only kills the pane, and the tmux session (and the ports) survive by design.

ss -ltn | grep -E ':(52080|52081|42998|42997|6430)'   # check binds
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:52081/api/v1/openapi.json
curl -s http://localhost:42998/version                # KMS liveness

Note: the KMS and Keycloak containers often report unhealthy in docker ps while serving fine — probe the HTTP endpoints, don't trust the healthcheck label.

The Orca browser and the user resolve localhost on Windows, and WSL2 only forwards IPv4 (0.0.0.0) binds. A server on the IPv6 wildcard (*:PORT in ss) works from inside WSL but gives ERR_EMPTY_RESPONSE / a chrome-error:// page in the browser.

• Backend and frontend already bind 0.0.0.0 — fine as-is.
• backlog browser binds the IPv6 wildcard on 6430 and has no --host flag, so it is invisible from Windows. Put an IPv4 relay in front of it:

socat TCP4-LISTEN:52091,bind=0.0.0.0,fork,reuseaddr TCP4:127.0.0.1:6430 &
# then open http://localhost:52091 on Windows

Always confirm the bind is 0.0.0.0:PORT (not *:PORT) before sending someone a URL.

pnpm dev:stop is the normal way — it kills the tmux session and then sweeps only the leftovers whose cwd is inside this repo. For anything it misses, kill by PID, never by name (other projects run the same binaries):

for p in 52080 52081 6430 52091; do
  ss -ltnp 2>/dev/null | grep ":$p " | grep -oP 'pid=\K[0-9]+' | head -1
done | xargs -r kill

PKI Manager uses Cosmian KMS for secure key storage. For development, a standalone Docker setup is provided.

cd kms
docker compose up -d

The KMS service runs on port 42998 (mapped from container's internal 9998).

curl http://localhost:42998/health

The KMS configuration is in kms/kms.toml:

The backend connects to KMS via environment variables in backend/.env:

KMS_URL=http://localhost:42998
# KMS_API_KEY=your-api-key-here (optional, for authenticated KMS)

# Server
PORT=52081
HOST=0.0.0.0
NODE_ENV=development

# Frontend URL for CORS
FRONTEND_URL=http://wsl.ymbihq.local:52080/

# Database
DATABASE_PATH=./data/pki.db

# Cosmian KMS
KMS_URL=http://localhost:42998

# SSH CA REST API without OIDC (dev only)
ALLOW_UNAUTHENTICATED_SSH_CA=true

# CRL Distribution Point
CRL_DISTRIBUTION_URL=http://wsl.ymbihq.local:52081/crl

With no OIDC_ISSUER/OIDC_AUDIENCE set the backend runs fully unauthenticated and logs OIDC authentication is disabled on boot — that is the default dev posture even when the Keycloak container is up. See OIDC.md to enable it.

VITE_API_URL=http://wsl.ymbihq.local:52081/trpc

From the project root:

pnpm dev

Use this when you can't give mprocs a TTY (scripts, agents, CI-ish runs):

pki-manager/
├── backend/
│   ├── src/
│   │   ├── server.ts               # Fastify server entry point
│   │   ├── trpc/
│   │   │   ├── router.ts           # Main tRPC router
│   │   │   ├── schemas.ts          # Zod validation schemas
│   │   │   └── procedures/         # API endpoints by domain
│   │   │       ├── ca.ts           # CA management
│   │   │       ├── certificate.ts  # Certificate operations
│   │   │       ├── dashboard.ts    # Dashboard stats
│   │   │       └── crl.ts          # CRL management
│   │   ├── db/
│   │   │   ├── schema.ts           # Drizzle ORM schema
│   │   │   ├── index.ts            # Database connection
│   │   │   └── migrations/         # SQL migrations
│   │   ├── kms/
│   │   │   └── client.ts           # Cosmian KMS client
│   │   └── crypto/                 # Certificate utilities
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── main.tsx                # App entry point
│   │   ├── routes/                 # TanStack Router routes
│   │   │   ├── __root.tsx          # Layout with navigation
│   │   │   ├── index.tsx           # Dashboard (/)
│   │   │   ├── cas.tsx             # CA list (/cas)
│   │   │   ├── cas.new.tsx         # Create CA (/cas/new)
│   │   │   ├── cas.$id.tsx         # CA details (/cas/:id)
│   │   │   ├── certificates.tsx    # Cert list (/certificates)
│   │   │   ├── certificates.new.tsx  # Issue cert (/certificates/new)
│   │   │   ├── certificates.$id.tsx  # Cert details (/certificates/:id)
│   │   │   └── certificates.bulk.tsx # Bulk creation (/certificates/bulk)
│   │   ├── components/             # React components
│   │   │   ├── theme-provider.tsx  # Theme context
│   │   │   └── theme-toggle.tsx    # Theme switcher
│   │   └── lib/
│   │       └── trpc.ts             # tRPC client setup
│   └── package.json
├── kms/
│   ├── docker-compose.yml          # Standalone KMS for development
│   ├── kms.toml                    # KMS configuration
│   └── data/                       # KMS SQLite data (gitignored)
├── docker/
│   └── docker-compose.yml          # Full stack for production
├── backlog/
│   ├── tasks/                      # Active task files
│   ├── docs/                       # Project documentation
│   ├── decisions/                  # Architecture decision records
│   ├── drafts/                     # Work-in-progress tasks
│   ├── completed/                  # Finished tasks
│   ├── archive/                    # Archived tasks
│   └── config.yml                  # Backlog configuration
├── tests/
│   └── screenshots.spec.ts         # Playwright screenshot tests
├── assets/                         # Screenshots for documentation
└── playwright.config.ts            # Playwright configuration

This project uses Backlog.md CLI for task management. Tasks track planned work, implementation plans, and acceptance criteria.

Backlog.md is installed globally (not as a project dependency):

# Install
npm install -g backlog.md

# Upgrade
npm update -g backlog.md

# Verify
backlog --version

Create a task when work requires planning or decision-making:

• Bug fixes that need investigation
• New features requiring design decisions
• Refactoring with architectural implications

Skip tasks for trivial changes:

• Typo fixes
• Version bumps
• Obvious one-line fixes

backlog/
├── tasks/        # Active tasks (To Do, In Progress)
├── docs/         # Project documentation and specs
├── decisions/    # Architecture Decision Records (ADRs)
├── drafts/       # Work-in-progress task drafts
├── completed/    # Finished tasks (Done status)
└── archive/      # Archived/cancelled tasks

# View tasks
backlog task list                    # List all active tasks
backlog task list --status "To Do"   # Filter by status
backlog task <id>                    # View task details
backlog search "keyword"             # Search tasks

# Create task
backlog task create "Title" -d "Description" --ac "Acceptance criterion"

# Task lifecycle
backlog task edit <id> -s "In Progress" -a @myself   # Start work
backlog task edit <id> --plan $'1. Step one\n2. Step two'  # Add plan
backlog task edit <id> --check-ac 1                  # Mark AC complete
backlog task edit <id> --notes "Summary of changes"  # Add PR notes
backlog task edit <id> -s Done                       # Complete task

# Documents
backlog doc list                     # List documents
backlog doc <id>                     # View document

1. Search first: Check for existing tasks before creating new ones
2. Create task: Define title, description, and acceptance criteria
3. Start work: Set status to "In Progress" and assign yourself
4. Plan: Add implementation plan before coding
5. Execute: Check off acceptance criteria as you complete them
6. Document: Add implementation notes (used for PR description)
7. Complete: Set status to "Done"

Acceptance criteria must be outcome-oriented and testable:

Use ANSI-C quoting for multi-line content:

backlog task edit <id> --plan $'1. First step\n2. Second step\n3. Third step'

Backlog includes a browser-based UI for visual task management:

# Start web interface (opens browser automatically)
backlog browser

# Custom port
backlog browser --port 8080

# Don't auto-open browser
backlog browser --no-open

Default port is 6430 (configurable in backlog/config.yml).

View tasks as a Kanban board in the terminal:

# Horizontal layout (default)
backlog board

# Vertical layout
backlog board --vertical

# Group by milestone
backlog board --milestones

# Export board to markdown
backlog board export board.md

Display project statistics and metrics:

backlog overview

• Use --plain flag for machine-readable output
• Multiple --ac flags add multiple acceptance criteria
• Multiple --check-ac flags check multiple criteria at once
• Tasks auto-commit to git when auto_commit: true in config
• Press Ctrl+C to stop the web interface

1. Define schema in backend/src/trpc/schemas.ts:

export const createCertificateSchema = z.object({
  caId: z.string().uuid(),
  subjectDn: z.string(),
  // ...
});

2. Add procedure in backend/src/trpc/procedures/certificate.ts:

export const certificateProcedures = {
  create: protectedProcedure
    .input(createCertificateSchema)
    .mutation(async ({ input, ctx }) => {
      // Implementation
    }),
};

3. Use in frontend:

const mutation = trpc.certificate.create.useMutation();
await mutation.mutateAsync({ caId, subjectDn, /* ... */ });

Create file in frontend/src/routes/:

# 1. Edit backend/src/db/schema.ts
# 2. Generate migration
cd backend && pnpm db:generate

# 3. Apply migration
pnpm db:migrate

cd backend && pnpm test

Automated screenshot testing with Playwright:

# Run all screenshot tests
pnpm test:screenshots

# Run with UI mode
pnpm test:screenshots:ui

# Run specific test
pnpm playwright test tests/screenshots.spec.ts -g "Dashboard"

Screenshots are saved to assets/ directory.

The project includes two Docker Compose configurations:

For production or integration testing with all services containerized:

cd docker
docker compose up -d

Services:

• KMS: Internal network only (port 9998)
• Backend: http://localhost:3000
• Frontend: http://localhost:8080

# Build both packages
pnpm build

# Start production servers
cd backend && pnpm start    # Backend
cd frontend && pnpm preview # Frontend preview