NinerLog API

RESTful backend for NinerLog — a free, open-source, EASA/FAA compliant digital pilot logbook with multi-license tracking, currency evaluation, and PDF export.

Tech Stack

• Go / Gin / PostgreSQL
• JWT (access + refresh tokens) with TOTP 2FA
• lib/pq (Postgres driver) / golang-migrate (schema migrations)
• oapi-codegen (OpenAPI server types) / kin-openapi (spec parsing)
• fpdf (PDF logbook export)

Prerequisites

• Go
• PostgreSQL
• Docker & Docker Compose (recommended)

Quick Start

# Start PostgreSQL
make docker-up

# Run migrations & start server
make run

# Run unit tests
make test

# Run integration tests (spins up test DB via Docker)
make test-integration

Make Targets

Target	Description
make run	Start the API server
make build	Build binary to bin/ninerlog-api
make generate	Generate Go types from OpenAPI spec
make test	Unit tests with coverage
make test-short	Unit tests (skip slow)
make test-integration	Integration tests (Docker test DB)
make test-e2e	End-to-end tests
make test-all	All tests
make coverage	Generate HTML coverage report
make lint	Run golangci-lint
make fmt	Format code
make migrate-up	Apply all pending migrations
make migrate-down	Roll back last migration
make migrate-create NAME=...	Create a new migration
make docker-up / docker-down	Manage Docker containers

Project Structure

cmd/api/main.go              # Entry point (config, DI, graceful shutdown)
internal/
├── api/
│   ├── generated/           # OpenAPI codegen output (do not edit)
│   ├── handlers/            # HTTP request handlers
│   └── middleware/          # CORS, request logging
├── airports/                # In-memory airport DB (OurAirports + mwgg, merged)
├── config/                  # Environment configuration
├── models/                  # Domain models
├── repository/
│   ├── interfaces.go        # Repository contracts
│   └── postgres/            # PostgreSQL implementations
├── service/                 # Business logic
│   ├── currency/            # EASA/FAA currency evaluators
│   └── flightcalc/          # Flight time & solar calculations
└── testutil/                # Test helpers & fixtures
pkg/
├── email/                   # SMTP email sender
├── hash/                    # Password hashing (bcrypt)
├── jwt/                     # JWT token management
└── solar/                   # Solar position calculations (night time)
db/migrations/               # SQL migrations (25 total)
test/e2e/                    # End-to-end tests

API Endpoints

Group	Endpoints
Auth	Register, login, refresh, password reset, 2FA setup/verify
User	Profile read/update
Licenses	CRUD, set default
Class Ratings	CRUD (per license)
Flights	CRUD with crew, block times, instrument tracking
Aircraft	CRUD
Credentials	CRUD (medicals, certificates)
Currency	Evaluate recency per license (EASA/FAA)
Notifications	List, mark read
Contacts	CRUD (crew/people)
Reports	Statistics, totals by time period
Maps	Airport search & lookup
Import	CSV flight log import
Export	Logbook PDF export

Environment Variables

See .env.example for a complete list of configuration options including database connection, JWT secrets, CORS settings, SMTP configuration, and TLS settings.

Single sign-on (optional). Setting OIDC_ISSUER switches the deployment to OIDC mode, where an external identity provider owns all accounts and NinerLog's own password, registration, 2FA and passkey endpoints are disabled. It is off by default. See docs/OIDC.md for configuration, provider recipes and migration.

Docker

# Build and run with Docker Compose
docker compose up -d

# Or build the image directly
docker build -t ninerlog-api .

Documentation

Full developer documentation lives in docs/. Start with the Developer Guide.

• Developer Guide — orientation and documentation map
• Architecture — layers, request lifecycle, wiring
• Data Model — entities, relationships, schema & migrations
• Aviation Domain — flights, time handling, validation, currency engine
• HTTP API — endpoints and the OpenAPI-first workflow
• Feature Catalogue — every feature, end to end
• Package Reference — internal/ and pkg/ packages
• Development Guide — setup, build, test, conventions
• Authentication — tokens, 2FA, WebAuthn
• OIDC Single Sign-On — optional external identity provider
• Metrics · Performance · Running Tests
• API Specification — OpenAPI 3.1 spec (source of truth)

Running NinerLog

To run your own NinerLog instance, see ninerlog for a ready-to-use Docker Compose setup with pre-built images.

Related Repositories

Repository	Description
ninerlog-frontend	React/TypeScript PWA frontend
ninerlog	Self-hosted deployment (Docker Compose)
ninerlog-website	Marketing website

Contributing

See CONTRIBUTING.md for development guidelines.

Security

To report a vulnerability, see SECURITY.md.

License

This project is licensed under the GNU Affero General Public License v3.0. See LICENSE.