diff --git a/.env.example b/.env.example index f4e58eb..b0565ec 100644 --- a/.env.example +++ b/.env.example @@ -1,14 +1,48 @@ -# Generate with: bin/rails secret +# Simple Aircraft Manager settings. Copy to .env and edit; only the first +# block is required. Every setting is explained in the README. + +# --- Required ---------------------------------------------------------- +# Generate with: bin/rails secret (or: openssl rand -hex 64) +# Keep a copy somewhere safe off the server: signatures and stored secrets +# depend on it, and a restore needs the same one. SECRET_KEY_BASE=change-me -# Public hostname, used in password-reset email links -APP_HOST=localhost:3000 -# "true" when behind HTTPS (reverse proxy / Kamal). "false" for plain HTTP on a LAN. -FORCE_SSL=false -# Optional: enable password-reset emails +# The host name people use to reach the app (used in email links). +APP_HOST=aircraft.example.com +# true: the app redirects to HTTPS and sets secure cookies (use behind a TLS +# proxy such as Traefik, Caddy or Cloudflare Tunnel). false: plain HTTP on a LAN. +FORCE_SSL=true + +# --- Address ----------------------------------------------------------- +# Full public URL, if it isn't https://APP_HOST (used for the single sign-on +# and Google Drive redirect URIs). +# APP_URL=https://aircraft.example.com + +# --- Email (password resets, sign-in links, invitations, reminders, alerts) # SMTP_ADDRESS=smtp.example.com # SMTP_PORT=587 # SMTP_USERNAME= # SMTP_PASSWORD= +# SMTP_TLS=false # true for TLS from the start (default on port 465) # MAIL_FROM=aircraft@example.com -# Optional: Claude transcribes scanned logbook pages + +# --- Single sign-on (OpenID Connect, e.g. Authentik) ---------------------- +# OIDC_ISSUER=https://auth.example.com/application/o/aircraft/ +# OIDC_CLIENT_ID= +# OIDC_CLIENT_SECRET= +# OIDC_PROVIDER_NAME=Authentik +# OIDC_AUTO_CREATE_USERS=false # true: create an account at first sign-in +# OIDC_TRUST_EMAIL=false # true: link accounts by unverified email +# OIDC_ADMIN_GROUP= # members become admins (synced at sign-in) +# PASSWORD_LOGIN=true # false: SSO only (invited mechanics then can't sign in) + +# --- Sign-in security ---------------------------------------------------- +# PWNED_PASSWORDS_CHECK=true # false if the server has no outbound internet + +# --- Logbook transcription with Claude ----------------------------------- # ANTHROPIC_API_KEY= +# LOGBOOK_AI_MODEL=claude-opus-5-5 +# LOGBOOK_AI_EFFORT=high + +# --- Other --------------------------------------------------------------- +# APP_REPOSITORY_URL= # source link on Admin → About (for a fork) +# RAILS_LOG_LEVEL=info diff --git a/README.md b/README.md index f708d65..bfe9b6d 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,13 @@ docker compose up -d --build # http://:3000 Data lives in the `sam_storage` volume. Set `FORCE_SSL=false` if you serve plain HTTP on a LAN. Set it to `true` when a TLS reverse proxy such as Caddy, Traefik, or Cloudflare Tunnel sits in front. +Other examples in the repository: + +- [`docker-compose.image.yml`](docker-compose.image.yml): runs a published image (set the image name to yours) without cloning the source, with a health check and update steps. +- [`docker-compose.traefik.yml`](docker-compose.traefik.yml): behind Traefik with HTTPS, with optional Authentik forward auth (see [Running behind Authentik](docs/authentik.md)). + +[`.env.example`](.env.example) lists every setting, grouped and commented. After starting or updating, `docker compose exec web bin/rails sam:doctor` checks the installation. + ### Option B: Kamal (any VPS, automatic TLS) Edit `config/deploy.yml` with your server IP, registry, and domain, then run `bin/kamal setup`. Kamal Proxy handles Let's Encrypt certificates. Background jobs run inside Puma (`SOLID_QUEUE_IN_PUMA`). diff --git a/docker-compose.image.yml b/docker-compose.image.yml new file mode 100644 index 0000000..0b51ab1 --- /dev/null +++ b/docker-compose.image.yml @@ -0,0 +1,30 @@ +# Run a published image, without cloning the source. +# +# 1. Put this file and a .env (copied from .env.example) in a folder. +# 2. Set the image below to the one you use. To publish your own: +# docker build -t your-registry/simple-aircraft-manager-rails:latest \ +# --build-arg APP_REVISION=$(git rev-parse --short HEAD) --build-arg APP_BUILT_AT=$(date -u +%FT%TZ) . +# docker push your-registry/simple-aircraft-manager-rails:latest +# 3. docker compose -f docker-compose.image.yml up -d +# 4. Open http://:3000 and create the admin account. +# +# Updating: docker compose -f docker-compose.image.yml pull && docker compose -f docker-compose.image.yml up -d +# (database changes are applied when the container starts). Then: docker compose exec web bin/rails sam:doctor +services: + web: + image: your-registry/simple-aircraft-manager-rails:latest + restart: unless-stopped + ports: + - "3000:80" + env_file: .env + environment: + SOLID_QUEUE_IN_PUMA: "true" # nightly backup, reminders and AD search run in the web process + volumes: + - sam_storage:/rails/storage # databases, uploaded files and nightly backups: back this up + healthcheck: + test: ["CMD", "curl", "-fsS", "http://localhost/up"] + interval: 30s + timeout: 5s + retries: 3 +volumes: + sam_storage: diff --git a/docker-compose.traefik.yml b/docker-compose.traefik.yml new file mode 100644 index 0000000..ab2904a --- /dev/null +++ b/docker-compose.traefik.yml @@ -0,0 +1,44 @@ +# Behind Traefik with HTTPS, optionally with Authentik forward auth in front. +# Assumes Traefik already runs with an entrypoint "websecure", a certificate +# resolver "letsencrypt", and a Docker network "proxy" shared with it. Adjust +# the names to your Traefik setup. In .env: APP_HOST=aircraft.example.com, FORCE_SSL=true. +# +# docker compose -f docker-compose.traefik.yml up -d +# +# Authentik: create the proxy provider and the unauthenticated URL list as in +# docs/authentik.md, then uncomment the middleware lines below. Leave them out +# to rely on the app's own sign-in (and optionally its single sign-on). +services: + web: + image: your-registry/simple-aircraft-manager-rails:latest # or: build: . + restart: unless-stopped + env_file: .env + environment: + SOLID_QUEUE_IN_PUMA: "true" + volumes: + - sam_storage:/rails/storage + networks: + - proxy + healthcheck: + test: ["CMD", "curl", "-fsS", "http://localhost/up"] + interval: 30s + timeout: 5s + retries: 3 + labels: + - traefik.enable=true + - traefik.docker.network=proxy + - traefik.http.routers.aircraft.rule=Host(`aircraft.example.com`) + - traefik.http.routers.aircraft.entrypoints=websecure + - traefik.http.routers.aircraft.tls.certresolver=letsencrypt + - traefik.http.services.aircraft.loadbalancer.server.port=80 + # --- Authentik forward auth (optional) --- + # - traefik.http.routers.aircraft.middlewares=authentik@docker + # The middleware itself is usually defined once, on the Authentik container: + # - traefik.http.middlewares.authentik.forwardauth.address=http://authentik-server:9000/outpost.goauthentik.io/auth/traefik + # - traefik.http.middlewares.authentik.forwardauth.trustForwardHeader=true + # - traefik.http.middlewares.authentik.forwardauth.authResponseHeaders=X-authentik-username,X-authentik-groups,X-authentik-email,X-authentik-name,X-authentik-uid +volumes: + sam_storage: +networks: + proxy: + external: true diff --git a/docker-compose.yml b/docker-compose.yml index 90b42bd..d04a592 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,8 @@ -# Simplest self-hosting: one container, SQLite + uploads in a named volume. +# Simplest self-hosting, built from this checkout: one container, SQLite and +# uploads in a named volume. To run a published image instead, see +# docker-compose.image.yml; behind Traefik (and Authentik), docker-compose.traefik.yml. # -# cp .env.example .env # set SECRET_KEY_BASE (bin/rails secret) and APP_HOST +# cp .env.example .env # set SECRET_KEY_BASE (bin/rails secret), APP_HOST, FORCE_SSL # docker compose up -d --build # open http://localhost:3000 → create the admin account services: @@ -14,5 +16,10 @@ services: SOLID_QUEUE_IN_PUMA: "true" # background jobs run inside the web process volumes: - sam_storage:/rails/storage # databases + uploaded files: back this up + healthcheck: + test: ["CMD", "curl", "-fsS", "http://localhost/up"] + interval: 30s + timeout: 5s + retries: 3 volumes: sam_storage: