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
🔧 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:

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

🛠️ 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

Made with ❤️ by Danny McClelland

Name		Name	Last commit message	Last commit date
Latest commit History 82 Commits
.github		.github
app		app
migrations		migrations
screenshots		screenshots
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
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
requirements.txt		requirements.txt
run.py		run.py

License

dannymcc/may

Folders and files

Latest commit

History

Repository files navigation

May