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

<p align="center"> <img src="screenshots/dashboard.png" alt="Dashboard" width="45%"> <img src="screenshots/vehicles.png" alt="Vehicles" width="45%"> </p> <p align="center"> <img src="screenshots/vehicle_details.png" alt="Vehicle Details" width="45%"> <img src="screenshots/integrations.png" alt="Integrations" width="45%"> </p> <p align="center"> <img src="screenshots/import_export.png" alt="Import/Export" width="45%"> </p>

🚀 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
• 🔧 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
• 📱 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 \
  ghcr.io/dannymcc/may:latest

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 (default: SQLite)
DATABASE_URL=sqlite:///data/may.db

# Upload folder for attachments
UPLOAD_FOLDER=/app/data/uploads

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | SECRET_KEY | Session encryption key | Random | | DATABASE_URL | Database connection string | sqlite:///data/may.db | | UPLOAD_FOLDER | Path for file uploads | /app/data/uploads | | 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

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

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
• Insurance
• Tax & Registration
• Parking & Tolls
• Accessories
• Other expenses

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
• MOT certificates
• Any file type with expiry date tracking

Fuel Stations

Save your favorite stations:

• Quick selection during fuel logging
• Track prices at different stations
• Notes and location information

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)
• 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

See the API documentation at /api/docs when logged in.

🔗 Integrations

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:

1. Go to Settings > Integrations > Calendar
2. Copy the webcal URL (for Apple Calendar, Outlook) or HTTPS URL (for Google Calendar)
3. 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 | 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 | | |

You can change your language