Carvey

Carvey

Docker app from Larv's Repository

Carvey is a self-hosted, local-first car maintenance tracker for managing vehicles, repairs, maintenance, MOTs, reminders and costs.

Overview
Carvey is a self-hosted, local-first car maintenance tracker for managing vehicles, repairs, maintenance, MOTs, reminders and costs.

Carvey Logo

Carvey is a self-hosted car maintenance tracker. It keeps the service history, MOTs, reminders, receipts and running costs for every car you own in one place. No accounts, no cloud: one SQLite database and an uploads folder.

Screenshots

Desktop

Garage Vehicle page (dark mode)

Costs

Mobile

Garage on mobile Vehicle page on mobile (dark mode) Reminders on mobile

Features

Garage

  • Any number of vehicles, each with a photo, plate, mileage, purchase details and notes
  • Garage overview: spend this year, open reminders, MOTs due soon and items to buy
  • Mark vehicles as sold

Per vehicle

  • Maintenance and Repairs: date, mileage, cost, category, garage/workshop and notes
  • MOTs: result, expiry and cost. Logging an MOT resets the MOT reminder
  • Renewals: insurance, road tax, warranty and breakdown cover, with provider, policy number, dates, cost and documents. Each type keeps a reminder on its renewal date
  • Fuel: fill-ups with volume, cost and odometer
  • Reminders: by date, mileage or both, with optional repeats. Mileage-only reminders get an estimated due date from how far the car is driven
  • Service Plan: reusable intervals (e.g. oil every 12 months / 6,000 miles) linked to reminders
  • To Buy: planned parts, which convert into a maintenance or repair entry when bought
  • Gallery and attachments: receipts, invoices and photos (PDF or image) on any record
  • Printable full service history

Across the garage

  • Reminders page: MOT expiry, renewals and every open reminder, grouped by overdue and upcoming
  • Notifications: a daily summary of what's coming up or due, sent to ntfy, Gotify, Apprise (email, Telegram, Slack and more), Discord or any webhook
  • Calendar feed: subscribe from Google, Apple or Outlook calendars to see reminders as all-day events
  • Costs page: spend by month, type and vehicle, per year or all time
  • Quick add: log anything for any vehicle from the bottom bar (mobile) or Add button (desktop)

App

  • Installable as a PWA, with mobile tab navigation and bottom-sheet forms
  • Light and dark mode, ten colour palettes, rounded or boxy shapes
  • One-click backup and restore (database and uploads in one zip, with a preview before restore)
  • Automatic nightly backups to data/backups/ (keeps the newest 3 by default)
  • CSV export (per record type or everything as a zip) and CSV import with column matching, duplicate detection and a preview before saving
  • Sign-in with optional two-factor authentication (authenticator app + recovery codes), a signed-in devices list, and a reverse-proxy mode for Authelia, Authentik and similar

Regional settings

Settings → Regional. Defaults are UK.

Setting Options
Currency Any ISO 4217 currency
Distance Miles · Kilometres
Fuel volume Litres · Gallons
Date format DD Mon YYYY · ISO 8601
Plate colour Yellow (rear) · White (front)
Annual test MOT · Inspection · Custom name · Disabled

Quick start

Docker Compose

docker compose up -d

Open http://localhost:3000 and create your admin account. Data is stored in ./data.

Local development (Node 24+)

npm install
CARVEY_DATA_DIR=./data npm run dev

To open the dev server from another device (a phone on your LAN), list its address: CARVEY_DEV_ORIGINS=192.168.1.20 npm run dev.

Environment variables

Variable Purpose
CARVEY_DATA_DIR Where the database and uploads are stored (/app/data in Docker)
TZ Time zone, e.g. Europe/London
CARVEY_RESET_PASSWORD Resets the admin password on startup (see below)
CARVEY_AUTH_MODE password (default), proxy or none. Overrides the sign-in toggle in Settings (see Sign-in and reverse proxies)
CARVEY_PROXY_SECRET Shared secret your proxy sends in proxy mode (16+ characters)
CARVEY_PROXY_SECRET_HEADER Header carrying the secret. Default X-Carvey-Proxy-Secret
CARVEY_PROXY_USER_HEADER Optional. Header with the signed-in user from your proxy, e.g. Remote-User. When set, requests without it are refused
CARVEY_ALLOWED_ORIGINS Extra origins allowed to post to Carvey, comma-separated. Only needed if your proxy rewrites the Host header without setting X-Forwarded-Host
CARVEY_TRUSTED_PROXY_HOPS How many proxies sit in front of Carvey (default 1). Used to read the real client address from X-Forwarded-For for sign-in rate limits. 0 ignores the header (no proxy)
CARVEY_SECURE_COOKIES true or false to force the session cookie's Secure flag. Default: on when the request arrived over HTTPS
CARVEY_RESET_2FA Set to true to turn off two-factor on startup (see below)
CARVEY_MAX_RESTORE_MB Largest backup file you can restore from the browser, in MB (default 256). The file is held in memory while it uploads, so leave headroom in the container's memory limit
CARVEY_DISABLE_SCHEDULER Set to true to stop the built-in scheduler: the daily notification check, nightly backups and data-folder clean-up (for example, when running several replicas)

Notifications and calendar

Settings → Notifications. Pick a service, paste its URL, then press Send test. Once a day, after the hour you choose (in the container's TZ), Carvey sends one summary of reminders that are due or coming up within your warning window. Each reminder is announced once when it's coming up and once when it falls due.

Service URL to enter
ntfy The full topic URL, e.g. https://ntfy.sh/my-private-topic. Add a token for protected topics
Gotify The server URL. Put the application token in Token
Apprise API The notify endpoint, e.g. http://apprise:8000/notify/carvey. Covers email, Telegram, Slack, Pushover and more
Discord The channel webhook URL
Webhook Any URL. Carvey POSTs JSON with title, body and an items array

Calendar feed: select Create calendar link and subscribe to it from your calendar app. The link works without a login, so treat it like a password; Reset link invalidates the old one.

Backups

Settings → Backup & Restore. Download backup gives you a zip of the database and every photo and document. Every night after 03:00 Carvey also saves one to the backups folder in its data directory and keeps the newest 3 (change it, or turn it off, on the same page). Those files sit on the same disk as the data, so copy the folder elsewhere with your usual backup tool. Any of them can be restored from the same page.

Carvey also tidies its data folder daily: unfinished restore previews and imports older than a day are removed, and only the 3 most recent pre-restore snapshots (restore-rollback/) are kept.

Importing from CSV

Settings → Import & Export. Choose what the file contains (maintenance, repairs, MOTs, fuel or renewals) and which vehicle it's for, or match rows by a registration column. Headers are matched by name, and common alternatives such as mileage, price or litres work. Dates can be ISO, day-first or month-first. A preview shows the columns used, the rows that will be skipped and why, and any rows already in Carvey, before anything is saved. Files exported from Carvey import back unchanged.

Sign-in and reverse proxies

Password (default). Sign in with your username and password. Turn on two-factor in Settings → Admin: scan the QR code with any authenticator app, then save the 10 recovery codes it gives you. Each recovery code works once.

Failed sign-ins are rate limited (5 per 15 minutes from one client, 25 per 15 minutes for the account). Browsers you've signed in from before are remembered for a year and keep their own limit, so someone guessing your password can't lock you out of your own devices. Re-entering your password or code in Settings → Admin is limited to 5 wrong tries per 15 minutes. Sessions last 30 days. Settings → Admin lists signed-in devices and can sign them out. Changing your password, or turning two-factor on or off, signs out every other device.

Behind a reverse proxy that handles sign-in (Authelia, Authentik, Cloudflare Access, oauth2-proxy, ...). Set:

environment:
  CARVEY_AUTH_MODE: proxy
  CARVEY_PROXY_SECRET: "<long random string, e.g. from: openssl rand -hex 32>"
  CARVEY_PROXY_USER_HEADER: Remote-User   # optional: require the user header your auth provider sets

Then have the proxy add the secret to every request it forwards to Carvey:

Proxy Config
Traefik headers middleware: customRequestHeaders: { X-Carvey-Proxy-Secret: "<secret>" }
Caddy reverse_proxy carvey:3000 { header_up X-Carvey-Proxy-Secret "<secret>" }
nginx proxy_set_header X-Carvey-Proxy-Secret "<secret>";
Others Add a custom request header with the same name and value, if your proxy supports it

Requests through the proxy are trusted. Requests without the secret, such as someone reaching the container port directly, still get the normal password and two-factor sign-in, so a published port is no longer an open door. Keep the secret out of anything the browser can see. If you set CARVEY_PROXY_USER_HEADER, make sure your proxy overwrites that header rather than passing a client's own value through.

No sign-in (CARVEY_AUTH_MODE=none, or the old Turn sign-in off option in Settings). Anyone who can reach Carvey has full access. Existing installs that used the toggle keep working, but turning it on now needs your password (and two-factor code), and restoring a backup never changes it. Prefer proxy mode.

Password and two-factor reset

From inside the container, with no restart:

docker exec -it <container-name> node scripts/reset-password.mjs                # new password
docker exec -it <container-name> node scripts/reset-password.mjs --disable-2fa  # turn off two-factor

Or set CARVEY_RESET_PASSWORD=newpassword and/or CARVEY_RESET_2FA=true, restart, log in, then remove the variables and restart again. Every reset signs out all existing sessions.

Tech stack

Next.js · React · TypeScript · SQLite (better-sqlite3) · Sharp · Vitest

Issues and feedback

Report bugs and feature requests here.

Categories

Related apps

Explore more like this

Explore all

Links

Details

Repository
ghcr.io/revise0592/carvey:latest
Last Updated2026-11-22
First Seen2026-05-06

Runtime arguments

Web UI
http://[IP]:[PORT:3000]
Network
bridge
Shell
sh
Privileged
false

Template configuration

App dataPathrw
Target
/app/data
Value
/mnt/user/appdata/carvey
Host Port 1Porttcp
Target
3000
Value
3000
TZVariable
Value
Europe/London