Pilot Service

Maritime pilot booking service for managing port pilot requests for vessels.

Quick Links

Service	URL	Credentials
Frontend	http://localhost:5173	-
Backend API	http://localhost:8000	-
API Docs	http://localhost:8000/docs	-
Keycloak Admin	http://localhost:8080	admin / admin

Demo user: demo / demo

Getting Started

1. Start Docker Services

docker compose up -d

This starts:

• PostgreSQL database for the application
• PostgreSQL database for Keycloak
• Keycloak server with pre-configured pilot realm

2. Start Backend

pip install -e ".[dev]"
uvicorn pilot.api:app --reload

The API runs on http://localhost:8000

3. Start Frontend

cd frontend
npm install
npm run dev

The frontend runs on http://localhost:5173

Features

• Port Management: Create and list ports with name, country, and UN/LOCODE
• Pilot Requests: Submit and track pilot service requests for vessels
• Authentication: Keycloak-based SSO with JWT tokens
• User Management: Self-service account management via Keycloak

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   React     │────▶│   FastAPI   │────▶│  PostgreSQL │
│  Frontend   │     │   Backend   │     │             │
└─────────────┘     └─────────────┘     └─────────────┘
       │                   │
       │                   │ JWT validation
       ▼                   ▼
┌─────────────────────────────────────┐
│            Keycloak                 │
│    (Identity & Access Management)   │
└─────────────────────────────────────┘

Environment Variables

Backend

Variable	Default	Description
DB_HOST	localhost	Database host
DB_PORT	5432	Database port
DB_USER	pilot	Database user
DB_PASSWORD	pilot_secret	Database password
DB_NAME	pilot_db	Database name
KEYCLOAK_SERVER_URL	http://localhost:8080	Keycloak server URL
KEYCLOAK_REALM	pilot	Keycloak realm
KEYCLOAK_CLIENT_ID	pilot-backend	Keycloak client ID

Frontend

Variable	Default	Description
VITE_KEYCLOAK_URL	http://localhost:8080	Keycloak server URL
VITE_KEYCLOAK_REALM	pilot	Keycloak realm
VITE_KEYCLOAK_CLIENT_ID	pilot-frontend	Keycloak client ID

Development

Running Tests

pytest

Linting Frontend

cd frontend
npm run lint

Keycloak Configuration

The Keycloak realm is automatically imported from keycloak/pilot-realm.json on first startup. To modify the configuration:

1. Make changes in the Keycloak admin console
2. Export the realm: Realm Settings → Action → Partial Export
3. Replace keycloak/pilot-realm.json with the exported file