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/                # OurAirports database loader
├── 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.

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
• Metrics · Performance · Running Tests
• API Specification — OpenAPI 3.1 spec (source of truth)

Running NinerLog

To run your own NinerLog instance, see ninerlog-dockerized 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.