ninerlog-api

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

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

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
• Aircraft Registrations — canonical registration notation
• 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

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.