May

A modern, self-hosted vehicle management application for tracking fuel consumption, expenses, reminders, and maintenance across your entire fleet.

Named after James May, completing the trio of Top Gear presenters (alongside Clarkson and Hammond).

📸 Screenshots

🚀 Features

🚗 Multi-Vehicle Support: Track cars, vans, motorbikes, and scooters with custom vehicle types
⛽ Fuel Logging: Record fill-ups with automatic consumption calculations (L/100km, MPG)
⚡ Quick Entry Mode: Rapid fuel logging with a streamlined interface
💰 Expense Tracking: Monitor maintenance, insurance, repairs, tax, and other costs by category
🔄 Recurring Expenses: Track regular payments like insurance, tax, and subscriptions
🔧 Maintenance Schedules: Plan and track scheduled maintenance with mileage/date intervals
📅 Reminders: Set up recurring reminders for MOT, service, insurance, and tax renewals
🔔 Multi-Channel Notifications: Get reminded via Email, ntfy, Pushover, or Webhooks
📁 Document Storage: Store important documents (insurance, registration, manuals) per vehicle
⛽ Favorite Stations: Save and quickly select your preferred fuel stations
👥 Multi-User: Share vehicles between family members or team members
📊 Analytics Dashboard: View spending trends and consumption statistics with interactive charts
📎 Attachment Support: Upload receipts and documents to fuel logs and expenses
📄 PDF Reports: Generate comprehensive vehicle reports for record-keeping, optionally with receipt images attached
🔧 Customizable Units: Support for metric/imperial, multiple currencies
🎛️ Menu Customization: Show/hide menu items and set your preferred start page
🌍 Internationalization: Available in multiple languages (English, German, Spanish, French, and more)
🎨 Custom Branding: Personalize with your own logo, colors, and app name
🌙 Dark Mode: Toggle between light and dark themes
📥 Import/Export: Import from Fuelly CSV, export all data as JSON or CSV
🇬🇧 DVLA Integration: Look up UK vehicle MOT and tax status automatically
⛽ UK Fuel Prices: Pull live forecourt prices for your saved UK stations from the government fuel price feeds, no API key needed
📱 PWA Support: Install as a mobile app with offline capabilities
🔌 REST API: Full API access for integrations and automation
🏠 Home Assistant Integration: Create sensors and automations for your vehicles
📆 Calendar Subscription: Subscribe to reminders in Apple Calendar, Google Calendar, Outlook
🐳 Docker Ready: Easy self-hosting via Docker

📦 Installation

Quick Start with Docker

# Create a directory for May
mkdir may && cd may

# Download docker-compose.yml
curl -O https://raw.githubusercontent.com/dannymcc/may/main/docker-compose.yml

# Start the container
docker compose up -d

Or run directly with Docker:

docker run -d \
  --name may \
  -p 5050:5050 \
  -v may_data:/app/data \
  -e SECRET_KEY=your-secret-key \
  -e PUID=1000 \
  -e PGID=1000 \
  ghcr.io/dannymcc/may:latest

Running as a specific user (PUID/PGID): May follows the linuxserver.io convention. Set the optional PUID and PGID environment variables to make the container run as a specific host user/group so bind-mounted data is owned correctly. They default to 1000:1000. On Unraid, set PUID=99 and PGID=100.

Access the application at http://localhost:5050

First-time login:

Username: admin
Password: Check your container logs for the auto-generated password

On first run, if no ADMIN_PASSWORD environment variable is set, May generates a secure random password and prints it to the console:

============================================================
SECURITY NOTICE: Default admin account created
Username: admin
Password: <randomly-generated-password>
Please change this password immediately after first login!
Set ADMIN_PASSWORD environment variable to avoid this message.
============================================================

To view the password, run:

docker logs may

💡 Tip: Set ADMIN_PASSWORD in your docker-compose.yml or environment to use a fixed password.

Manual Installation

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the application
python run.py

⚙️ Configuration

Copy .env.example to .env and configure:

# Secret key for session encryption
SECRET_KEY=your-secure-random-string

# Database location (optional, defaults to SQLite in the app's data folder)
# Note the slashes: sqlite:///path is relative, sqlite:////path is absolute.
DATABASE_URL=sqlite:////srv/may/data/may.db
# PostgreSQL is also supported:
# DATABASE_URL=postgresql://user:password@host:5432/may

# Upload folder for attachments (optional)
UPLOAD_FOLDER=/srv/may/data/uploads

The .env file must sit next to config.py in the application directory, and it is read when May starts. Variables set in the real environment take precedence over .env.

Under Docker Compose, .env is only used for ${VAR} substitution in docker-compose.yml (for example SECRET_KEY). DATABASE_URL and UPLOAD_FOLDER are set in the compose environment: block, so changing them in .env has no effect — edit docker-compose.yml instead.

Environment Variables

Variable	Description	Default
`SECRET_KEY`	Session encryption key	Random
`DATABASE_URL`	Database connection string (SQLite or PostgreSQL)	SQLite at `data/may.db` inside the application directory (`/app/data/may.db` in Docker)
`UPLOAD_FOLDER`	Path for file uploads	`data/uploads` inside the application directory (`/app/data/uploads` in Docker)
`PUID`	User ID the container runs as (linuxserver.io convention)	`1000`
`PGID`	Group ID the container runs as (linuxserver.io convention)	`1000`
`TAILWIND_ASSET_URL`	Local Tailwind Play CDN JS path	`/static/vendor/tailwindcss.js`
`TAILWIND_CDN_URL`	Tailwind CDN fallback URL	`https://cdn.tailwindcss.com`
`HTMX_CDN_URL`	HTMX CDN URL	`https://unpkg.com/htmx.org@1.9.10`

By default, Tailwind loads from app/static/vendor/tailwindcss.js and falls back to the CDN URL if the local asset is missing.

🎯 Usage

Dashboard

The main dashboard shows an overview of all your vehicles with key statistics:

Total fuel costs and consumption averages
Recent fuel logs and expenses
Upcoming reminders and overdue alerts
Vehicle photo cards showing make/model/year and fuel type at a glance

Vehicles

Add and manage your vehicles with detailed information:

Make, model, year, and registration
Fuel type and tank capacity
Custom specifications and notes
Photo upload support
Vehicle Sharing: Mark a vehicle as "Shared" to make it visible and loggable by all users on the instance
Upcoming Maintenance: Vehicle detail pages show a live panel of scheduled maintenance tasks, with overdue and due-soon alerts
Parts & Consumables: Collapsible section on the vehicle page remembers your expand/collapse preference per vehicle
PDF Report: The "PDF" button downloads a summary of the vehicle, its specifications, its parts and consumables, its fuel logs and its expenses. "PDF + Receipts" does the same and appends the receipt images attached to those entries, which is the version to hand to an accountant or employer. Non-image attachments (PDF scans, for example) are listed at the end of the report rather than embedded.

Fuel Logs

Track every fill-up with:

Date, odometer reading, and fuel amount
Total cost and price per unit
Full tank indicator for accurate consumption calculations
Automatic MPG/L per 100km calculations

Expenses

Categorize all vehicle-related costs:

Maintenance & Repairs
Inspection (MOT, roadworthy checks)
Insurance
Tax & Registration
Parking & Tolls
Accessories
Other expenses

Record odometer readings alongside costs, and expand any expense row to see vendor, notes, and links to any attached receipts inline. An expense can have several receipts — select more than one file when adding or editing it.

Reminders

Never miss important dates:

MOT/Inspection due dates
Service intervals
Insurance renewals
Tax payments
Custom reminders with flexible recurrence

Maintenance Schedules

Plan regular maintenance tasks:

Set intervals by mileage or time (e.g., oil change every 10,000 km or 12 months)
Track completion history
Automatic reminder generation
Link to expenses when completed

Recurring Expenses

Track regular payments:

Insurance premiums
Road tax
Subscriptions and memberships
Custom recurrence patterns (monthly, quarterly, yearly)
Automatic calendar integration

Documents

Store important vehicle documents:

Insurance certificates
Registration documents
Service manuals and instruction booklets (up to 300MB)
MOT certificates
Any file type (PDF, images, Word, Excel, text, ePub) with expiry date tracking

Fuel Stations

Save your favorite stations:

Quick selection during fuel logging
Track prices at different stations
Notes and location information
UK stations can pull live prices from the government fuel price feeds (see UK Fuel Prices)

Notifications

Configure your preferred notification method:

Email: SMTP server configuration (admin)
ntfy: Free push notifications via ntfy.sh or self-hosted
Pushover: iOS/Android push notifications
Webhook: HTTP POST for Home Assistant, Discord, Slack, etc.

🔧 Admin Settings

Administrators can configure:

SMTP Settings: Email server for notifications
Pushover: Application token for push notifications
DVLA API: API key for UK vehicle lookups (get one here)
UK Fuel Prices: live forecourt prices for saved stations (see below)
Branding: Custom logo, app name, tagline, and primary color
User Management: Create, edit, and manage user accounts

🔌 API

May includes a REST API for automation and integrations:

# Generate an API key in Settings > API
curl -H "Authorization: Bearer may_your_api_key" \
  http://localhost:5050/api/v1/vehicles

Vehicles, fuel logs, expenses, trips, and charging sessions can all be read and created through the API. See the API documentation at /api/docs when logged in.

🔗 Integrations

UK Fuel Prices

UK retailers publish their forecourt prices as open JSON feeds under the government fuel price transparency scheme. May can read those feeds and record the prices against your saved stations, so price history and Cheapest Fuel stay current without manual entry. No API key is needed.

To use it:

An admin enables it in Settings → Integrations → UK Fuel Prices.
Give each saved station its postcode — that is what stations are matched on. Where a postcode covers more than one forecourt, coordinates (if set) and then brand break the tie.
Prices refresh in the background every six hours, and on demand with the Update UK Prices button on the Fuel Stations page or on a single station's price history.

Prices are stored one row per station, fuel type and day, so re-running the refresh updates the day's entry rather than adding duplicates. Premium grades are recorded separately (E5 as "Petrol Premium", SDV as "Diesel Premium").

The built-in retailer list follows the gov.uk guidance page. Retailers join and leave the scheme, so the settings panel takes an optional override — one feed per line, either Retailer name|https://... or a bare URL. A feed that is unreachable is reported and the rest still apply.

Home Assistant

Create vehicle sensors in Home Assistant:

sensor:
  - platform: rest
    name: "May Vehicle Stats"
    resource: http://your-may-instance/api/ha/summary
    headers:
      Authorization: Bearer may_your_api_key
    value_template: "{{ value_json.alerts_count }}"
    json_attributes:
      - total_vehicles
      - total_cost

Available endpoints: /api/ha/status, /api/ha/vehicles, /api/ha/alerts, /api/ha/summary

Calendar Subscription

Subscribe to reminders in your calendar app:

Go to Settings > Integrations > Calendar
Copy the webcal URL (for Apple Calendar, Outlook) or HTTPS URL (for Google Calendar)
Add as a subscribed calendar in your app

The calendar includes:

Maintenance schedules
Recurring expense due dates
Document expiry dates
Custom reminders

🌍 Supported Languages

May is available in the following languages:

Language	Code	Language	Code
English	`en`	Swedish (Svenska)	`sv`
German (Deutsch)	`de`	Danish (Dansk)	`da`
Spanish (Español)	`es`	Norwegian (Norsk)	`no`
French (Français)	`fr`	Finnish (Suomi)	`fi`
Italian (Italiano)	`it`	Japanese (日本語)	`ja`
Dutch (Nederlands)	`nl`	Chinese (中文)	`zh`
Portuguese (Português)	`pt`	Korean (한국어)	`ko`
Polish (Polski)	`pl`	Czech (Čeština)	`cs`
Russian (Русский)	`ru`	Turkish (Türkçe)	`tr`
Arabic (العربية)	`ar`

You can change your language in Settings > Units & Values > Language.

Improving Translations

Translations were generated with AI assistance and may contain inaccuracies. If you spot an incorrect translation, contributions are very welcome:

Translation files are located in app/translations/<lang>/LC_MESSAGES/messages.po
Edit the msgstr value for any incorrect entry
Submit a pull request with your fix

🛠️ Tech Stack

Backend: Python / Flask
Database: SQLite (easily swappable)
Frontend: Tailwind CSS, HTMX, Chart.js
Server: Gunicorn
Notifications: SMTP, ntfy, Pushover, Webhooks
PDF Generation: WeasyPrint

🐛 Troubleshooting

Application Won't Start

Check that all dependencies are installed: pip install -r requirements.txt
Ensure the data directory is writable
Check logs for specific error messages

Database Issues

Default SQLite database is created at data/may.db
Ensure the directory exists and is writable
For schema updates, the app handles migrations automatically

Notification Issues

Email: Verify SMTP settings and credentials in admin settings
ntfy: Check your topic name is correct
Pushover: Ensure admin has configured the app token
Webhook: Verify the URL is accessible and accepts POST requests

PDF Generation

WeasyPrint requires system dependencies on some platforms
On Ubuntu/Debian: apt-get install libpango-1.0-0 libpangocairo-1.0-0
On macOS: brew install pango

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

Clone this repository
Create a virtual environment: python3 -m venv venv
Activate it: source venv/bin/activate
Install dependencies: pip install -r requirements.txt
Run in development mode: python run.py

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

Issues: GitHub Issues
Documentation: This README and in-app help

🙏 Acknowledgments

App icon design by @lancetm714

Made with ❤️ by Danny McClelland

Name		Name	Last commit message	Last commit date
.github		.github
app		app
migrations		migrations
screenshots		screenshots
scripts		scripts
tests		tests
.coderabbit.yaml		.coderabbit.yaml
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
babel.cfg		babel.cfg
config.py		config.py
docker-compose.staging.yml		docker-compose.staging.yml
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
pytest.ini		pytest.ini
requirements.txt		requirements.txt
run.py		run.py

Latest commit

History

Folders and files

Repository files navigation

May