https://github.com/dannymcc/may
May is a web-based dashboard application that gives you a neat and clean interface for logging your fuel fill-ups for all of your vehicles. The application has full multi-user support, as well as multiple vehicles per user. Whenever you fill-up your car or motorcycle, keep the receipt and record the data in May.
https://github.com/dannymcc/may
docker flask fleet fuel maintenance python self-hosted vehicle
Last synced: about 1 month ago
JSON representation
May is a web-based dashboard application that gives you a neat and clean interface for logging your fuel fill-ups for all of your vehicles. The application has full multi-user support, as well as multiple vehicles per user. Whenever you fill-up your car or motorcycle, keep the receipt and record the data in May.
- Host: GitHub
- URL: https://github.com/dannymcc/may
- Owner: dannymcc
- License: mit
- Created: 2026-01-29T11:55:26.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-27T16:41:38.000Z (about 1 month ago)
- Last Synced: 2026-04-27T18:27:27.143Z (about 1 month ago)
- Topics: docker, flask, fleet, fuel, maintenance, python, self-hosted, vehicle
- Language: HTML
- Size: 3.01 MB
- Stars: 183
- Watchers: 1
- Forks: 19
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# May
[](https://buymeacoffee.com/d3hkz6gwle)
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](https://github.com/linuxserver/Clarkson) and [Hammond](https://github.com/AlfHou/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
```bash
# 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:
```bash
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:
Please change this password immediately after first login!
Set ADMIN_PASSWORD environment variable to avoid this message.
============================================================
```
To view the password, run:
```bash
docker logs may
```
π‘ **Tip:** Set `ADMIN_PASSWORD` in your docker-compose.yml or environment to use a fixed password.
### Manual Installation
```bash
# 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:
```bash
# 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
- 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
### 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 and notes details inline.
### 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
### 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](https://developer-portal.driver-vehicle-licensing.api.gov.uk/))
- **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:
```bash
# 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:
```yaml
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 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:
1. Translation files are located in `app/translations//LC_MESSAGES/messages.po`
2. Edit the `msgstr` value for any incorrect entry
3. 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
1. Clone this repository
2. Create a virtual environment: `python3 -m venv venv`
3. Activate it: `source venv/bin/activate`
4. Install dependencies: `pip install -r requirements.txt`
5. Run in development mode: `python run.py`
## π License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## π Support
- **Issues**: [GitHub Issues](https://github.com/dannymcc/may/issues)
- **Documentation**: This README and in-app help
## π Acknowledgments
- App icon design by [@lancetm714](https://github.com/lancetm714)
---
**Made with β€οΈ by [Danny McClelland](https://github.com/dannymcc)**