# Frequently Asked Questions (FAQ)

Common questions and answers about MyGarage installation, configuration, and usage.

---

## General Questions

### What is MyGarage?

MyGarage is a self-hosted vehicle maintenance tracking application. It helps you track service records, fuel economy, documents, and reminders for all your vehicles in one place.

### Is MyGarage free?

Yes! MyGarage is 100% free and open-source under the MIT License. You can use it, modify it, and even distribute it without any cost.

### Do I need to know programming to use MyGarage?

No. If you can run Docker containers, you can use MyGarage. The Quick Start guide gets you running in under 5 minutes.

### Can I use MyGarage for a business or fleet?

The MIT License allows any use, but MyGarage is built for households: the
vehicles you and your family own and maintain yourselves. It has no fleet, shop
or customer features, such as invoicing, labor billing or purchase orders.

### Is my data safe and private?

Yes. MyGarage is self-hosted - **all data stays on your server**. Only features that need an outside service contact one; see [Does MyGarage send my data anywhere?](#does-mygarage-send-my-data-anywhere). OCR runs locally.

### Can I access MyGarage from my phone?

Yes. MyGarage has a responsive web interface that works on mobile browsers. There's no native app yet, but the web version is fully mobile-optimized.

---

## Installation & Setup

### What are the system requirements?

**Minimum**:
- CPU: 1 core
- RAM: 512MB
- Disk: 2GB
- OS: Linux, Windows, macOS (anything that runs Docker)

**Recommended**:
- CPU: 2 cores
- RAM: 1GB
- Disk: 10GB (for photos and documents)

### Can I install MyGarage without Docker?

Yes. See the [Installation Guide](Installation.md#bare-metal-installation) for bare metal installation instructions. You'll need Python 3.14+ and Bun 1.4.2+.

### Does MyGarage work on Raspberry Pi?

No. The published `ghcr.io/homelabforge/mygarage:latest` image is amd64-only, so it won't run on ARM boards like the Raspberry Pi. Run it on an x86-64 host, or build your own ARM image from source.

### Can I install MyGarage on Synology or QNAP NAS?

Yes! See platform-specific instructions:
- [Synology NAS Installation](Installation.md#synology-nas-installation)
- QNAP: Similar process via Container Station

### How do I update MyGarage?

**Docker Compose**:
```bash
docker-compose pull
docker-compose up -d
```

**Docker Run**:
```bash
docker stop mygarage
docker rm mygarage
docker pull ghcr.io/homelabforge/mygarage:latest
docker run -d \
  --name mygarage \
  -p 8686:8686 \
  -v $(pwd)/data:/data \
  ghcr.io/homelabforge/mygarage:latest
```

### Will updates delete my data?

No. Your data is stored in the `/data` volume, which persists across container updates. Always backup before major updates as a precaution.

---

## Authentication & Security

### Why does MyGarage warn about "No Authentication"?

By default, MyGarage starts with authentication disabled for easy initial setup. This is **not secure for public-facing deployments**. Enable `local` or `oidc` auth mode before exposing to the internet.

### How do I enable authentication?

See the [Authentication Guide](Authentication). TL;DR: open **Settings → System**. In the **Authentication Mode** card, click the **Local** tab, then **Switch to local sign-in**, and confirm. For SSO, click the **OIDC** tab, then **Configure OIDC**, fill it in and **Save**, then **Switch to SSO** and confirm. The change takes effect at once, with no restart or environment variables. In Local mode, register the first account from the sign-in page.

### I forgot my password. How do I reset it?

**If you're the only user**:
1. Stop MyGarage
2. Delete the database file (WARNING: loses all data)
3. Restart MyGarage
4. Re-register with new password
5. Restore data from backup

**If you have an admin account**:
- Admin can reset passwords in **Settings → System → Manage Family**, with **Reset password** (key icon) on the member's card

**Better option**: Switch to OIDC/SSO for centralized password management.

### Can I use Google/Microsoft/Okta for login?

Yes! MyGarage supports OIDC/OAuth2 authentication. See [Authentication - OIDC Configuration](Authentication.md#oidcsso-authentication).

### Is HTTPS required?

**For production: Yes.** HTTPS is required for:
- Secure JWT cookies
- OIDC authentication
- Protecting sensitive data (insurance, VINs)

See [Reverse Proxy Configuration](Reverse-Proxy) for HTTPS setup.

---

## Features & Usage

### Can MyGarage track multiple vehicles?

Yes! There's no limit. Track as many vehicles as you want (cars, motorcycles, boats, RVs, etc.).

### Does MyGarage support electric vehicles (EVs)?

**Yes!** MyGarage supports Electric and Hybrid vehicles with smart charging tracking:

- **Electric vehicles** — Track kWh charged, charging costs, efficiency (kWh/100mi)
- **Hybrid vehicles** — Track both gallons AND kWh for plug-in hybrids
- **Smart form** — UI adapts based on vehicle type (hides/shows relevant fields)

See [Fuel Tracking - Electric Vehicles](Fuel-Tracking.md#electric-vehicles-evs) for details.

### Can I track fuel in liters instead of gallons?

Yes. Set **Metric** under **Unit System** in **Quick settings** (the gear icon) and fuel, distance, and economy display in liters, kilometers, and L/100km. You can also mix them: **Custom** sets each quantity separately, so litres with miles, or PSI on an otherwise metric account, are both valid. A vehicle can also have its own **Odometer unit** (km or mi) in its edit form. Values are stored in metric-canonical units, so switching units doesn't lose precision. See [Units](Units).

### Can I type a comma as the decimal separator?

Yes, since v3.0.1. Number fields accept either separator, so `528,25` and `528.25`
are both read as the same value. This matters most on a phone, where the keyboard
often offers only the separator matching your system locale.

Thousands separators are understood too — `1 234,56`, `1.234,56` and `1,234.56`
all work. If a value is genuinely ambiguous, your selected language decides how
it's read.

### Does MyGarage track DEF (Diesel Exhaust Fluid)?

Yes, for diesel vehicles. Fill-ups, tank level, consumption rate, and cost appear on a dedicated DEF tab, with optional low-DEF alerts. DEF is diesel-only; other vehicles don't see it.

### What extra details can I log on a fuel fill-up?

Beyond odometer, volume, and cost, a fill-up can record time, station, driver, payment method, trip type, outside temperature, and trip-computer (OBC) values. "Auto-fill from last drive" pulls OBC values from the most recent LiveLink drive session.

### How does VIN decoding work?

MyGarage queries the [NHTSA vPIC API](https://vpic.nhtsa.dot.gov/api/) (free public service) to decode VINs. This works for vehicles sold in the United States. International vehicles may have limited support.

### VIN decoding doesn't work for my vehicle. Why?

**Possible Reasons**:
- **Non-US vehicle** - NHTSA database only covers US market vehicles
- **Old vehicle** - Vehicles older than 1981 may not be in the database
- **Commercial vehicle** - Some commercial vehicles, RVs, motorcycles have limited data
- **Invalid VIN** - Verify the 17-character VIN is correct

**Solution**: Use manual entry for vehicles that don't decode.

### Can I import data from other apps (Fuelio, Drivvo, etc.)?

Yes, for fuel records from **Fuelio**, **Drivvo** and **Tesla / ABRP**. Open the
vehicle's **Fuel** tab, choose **Import**, and pick the format. Columns are
matched by name, so there is no mapping step. A file from any other app imports
once it uses MyGarage's own CSV columns; export a record first to see them. See
[Fuel Tracking](Fuel-Tracking#importing-from-another-app).

### Does MyGarage send reminders automatically?

Yes. Set `SCHEDULER_ENABLED=true` and configure a notification backend. A background scheduler checks for due/overdue maintenance, insurance/warranty expiry, NHTSA recalls, and odometer milestones, and sends notifications via ntfy, Gotify, Pushover, Slack, Discord, Telegram, Matrix, or email (Settings → Notifications).

### Can I share my garage with family members?

Yes! Use `auth_mode=local` or `auth_mode=oidc` and create user accounts for family members. Vehicles can be shared with all users or assigned to specific users. Members who aren't admins see only their own settings; the Files, Notifications and Backup tabs are hidden from them.

### Can I export my data?

Yes, per vehicle, from the vehicle's page:
- **JSON** - The vehicle and most of its records (see [Exporting Vehicle Data](Managing-Vehicles.md#exporting-vehicle-data) for what it leaves out)
- **CSV** - Service records, fuel logs and other records
- **PDF** - Reports

For a backup of everything, use **Settings → Backup & Restore**.

---

## LiveLink & Telemetry

### What is LiveLink?

LiveLink is MyGarage's real-time vehicle telemetry integration. It takes data from WiCAN OBD2 devices, the Torque Pro app, and MQTT sensors (such as Mopeka propane tank sensors), providing live data, drive session tracking, diagnostic trouble codes, and automatic odometer updates.

See the full [LiveLink Guide](LiveLink) for setup and usage.

### What hardware do I need for LiveLink?

For OBD2 data, a **WiCAN** device from [MeatPi Electronics](https://www.meatpi.com/products/wican), or the **Torque Pro** app with its OBD2 adapter. MQTT sensors need an MQTT broker.

| Device | HTTPS POST | MQTT | Price |
|--------|------------|------|-------|
| **WiCAN PRO** (recommended) | ✅ Yes | ✅ Yes | ~$50 |
| **Standard WiCAN** | ❌ No | ✅ Yes | ~$35 |

The WiCAN PRO is recommended because it supports both transport methods. Standard WiCAN requires an MQTT broker.

### Can I use LiveLink with any OBD2 scanner?

Not directly. LiveLink takes OBD2 data from **WiCAN devices** (HTTPS POST or MQTT) and from the **Torque Pro** app. A generic Bluetooth OBD2 scanner (like an ELM327) works only through Torque Pro.

### What's the difference between HTTPS POST and MQTT?

| Aspect | HTTPS POST | MQTT |
|--------|------------|------|
| **Setup** | Simpler (direct to MyGarage) | Requires MQTT broker |
| **Latency** | Higher (new connection each request) | Lower (persistent connection) |
| **Device Support** | WiCAN PRO only | All WiCAN devices |
| **Remote Access** | Works over internet | LAN only (unless broker is exposed) |

You can run both, but pick one for telemetry: the two stamp readings differently, so a reading sent both ways is stored twice. See [Running Both Simultaneously](LiveLink#running-both-simultaneously).

### Does LiveLink work when I'm away from home?

**Partially.** WiCAN devices require WiFi to transmit data. When your vehicle is away from WiFi range:

- ❌ No live telemetry reaches MyGarage
- ❌ Drive sessions during this time have gaps
- ✅ Data resumes when you return to WiFi range

When the device reconnects to WiFi, MyGarage backfills the gap from the WiCAN's SD-card log (SD-equipped devices) — automatically on reconnect, or via a manual admin trigger — so drives away from home are filled in after the fact.

### Why are there gaps in my telemetry data?

Gaps occur when the WiCAN device loses WiFi connectivity — typically when the vehicle is away from home. On reconnect, MyGarage backfills the gap from the device's SD-card log (SD-equipped WiCAN devices), so most gaps fill in automatically once you return to WiFi range.

### How much storage does LiveLink telemetry use?

It depends on:
- Number of parameters being polled
- Polling interval (typically 5 seconds)
- How much you drive

**Rough estimate**: 10-50 MB per vehicle per month with typical usage.

Configure retention periods (30-365 days) under **LiveLink settings** (the gear on the LiveLink card in Settings → Integrations) to manage storage. Daily aggregation preserves trends even after raw data is purged.

### Why is my device showing as "offline"?

"Device offline" means MyGarage hasn't received data from the WiCAN for the configured timeout (default 15 minutes).

**Possible causes:**
- Vehicle is away from WiFi
- WiCAN lost power (vehicle battery disconnected)
- WiFi network issues
- Incorrect token or endpoint configuration

### What are "phantom devices"?

Before v3.10.0, MyGarage created a device from an old retained MQTT message when it subscribed. Retained messages are ignored now, so they no longer create devices.

**Solution:** delete any phantom devices left by an earlier version. See [LiveLink Troubleshooting](LiveLink.md#phantom-devices).

### Why isn't my odometer syncing?

Odometer sync requires:
1. Your vehicle supports an odometer PID (not all do)
2. WiCAN's AutoPID includes the correct odometer PID for your make/model
3. The device is linked to a vehicle in MyGarage

Some vehicles (especially older or non-US models) don't expose odometer via OBD2. You may need manufacturer-specific PIDs.

### Can I use LiveLink with multiple vehicles?

Yes! Each vehicle needs its own WiCAN device. Link each device to its vehicle in Settings → Integrations: open the device's tab on the LiveLink card and its settings (for example **WiCAN settings**).

---

## Database Questions

### Should I use SQLite or PostgreSQL?

**Use SQLite** (default) if:
- Single user or small family (< 5 users)
- Small garage (< 10 vehicles)
- Homelab deployment

**Use PostgreSQL** if:
- Multi-user (10+ users)
- Large garage (50+ vehicles)
- High traffic (hundreds of requests/day)

See [Database Configuration](Database-Configuration) for details.

### Can I migrate from SQLite to PostgreSQL later?

Not with a built-in tool. A full restore from the app only runs on SQLite,
into SQLite, and a vehicle's JSON export carries only some of its records. See
[Database Configuration - Migration](Database-Configuration.md#migrating-from-sqlite-to-postgresql).

### How do I backup my data?

Easiest: **Settings → Backup & Restore**. Backups work on both databases (SQLite backups use the Online Backup API, so they're safe while the app is running); a full restore from there works on SQLite only. A full restore from there finishes when MyGarage restarts: see [Restore SQLite](Database-Configuration.md#restore-sqlite).

Manual:
```bash
# SQLite — stop the container first (a live copy is a torn copy under WAL)
docker-compose stop mygarage && cp data/mygarage.db data/mygarage-backup.db && docker-compose start mygarage

# PostgreSQL
docker exec mygarage-postgres pg_dump -U mygarage mygarage > backup.sql
```

See [Database Configuration - Backups](Database-Configuration.md#database-backups).

### Where is my data stored?

**SQLite**: `/data/mygarage.db` (inside container)

**PostgreSQL**: Inside the `postgres_data` Docker volume

**Uploads** (photos, documents): `/data/uploads/` (inside container)

**Docker Volume Mapping**: `./data:/data` maps container `/data` to host `./data` directory.

---

## Performance & Scalability

### How many vehicles can MyGarage handle?

- **SQLite**: 50-100 vehicles comfortably
- **PostgreSQL**: 1,000+ vehicles

Tested with up to 10,000 service records without performance issues.

### How many users can MyGarage support?

- **SQLite**: 5-10 concurrent users
- **PostgreSQL**: 100+ concurrent users

### Why is MyGarage slow?

**Possible Causes**:
1. **Large database** - Too many records for SQLite → Migrate to PostgreSQL
2. **Low resources** - Increase Docker memory limit
3. **Slow disk** - Use SSD instead of HDD
4. **Network latency** - Check network between client and server

**Diagnostics**:
```bash
# Check Docker resource usage
docker stats mygarage

# Check database size
ls -lh data/mygarage.db

# Optimize SQLite (the image has no sqlite3 command, so this uses Python)
docker exec mygarage python3 -c "import sqlite3; sqlite3.connect('/data/mygarage.db').execute('VACUUM')"
```

### Can I run multiple MyGarage instances?

Yes, but:
- Each instance needs its own database (or shared PostgreSQL database with connection pooling)
- Use load balancer (HAProxy, Traefik) to distribute traffic
- Shared file storage required for uploads (NFS, S3, etc.)

**Not recommended** unless you have advanced DevOps needs.

---

## Troubleshooting Common Issues

### Container won't start

**Check logs**:
```bash
docker logs mygarage
```

**Common Issues**:
- Port 8686 already in use → Change port in `docker-compose.yml`
- Database connection error → Verify `MYGARAGE_DATABASE_URL` if using PostgreSQL
- Permission errors → Ensure `/data` volume is writable

### "502 Bad Gateway" when using reverse proxy

**Cause**: Reverse proxy can't reach MyGarage container

**Fix**:
- Verify MyGarage is running: `docker ps | grep mygarage`
- Check health endpoint: `curl http://localhost:8686/health`
- Verify reverse proxy and MyGarage are on same Docker network

See [Reverse Proxy Configuration](Reverse-Proxy.md#troubleshooting).

### MPG not calculating

**Cause**: MPG requires 2+ full tank fill-ups

**Fix**:
- Ensure **Full Tank Fill-up** is checked on fill-ups
- Verify accurate odometer readings
- Check you have at least 2 fill-ups (first fill is baseline)

See [Fuel Tracking](Fuel-Tracking.md#understanding-mpg-calculations).

### An import doesn't read my document

OCR only fills in a form from an upload: **Import from PDF** on an insurance
policy, **Upload Window Sticker** on a vehicle, and, if you turn on the LLM
receipt parser in **Settings → Integrations**, **Parse receipt** on a fuel entry. Stored documents are never read or indexed.

A window sticker upload isn't scanned while **Enable OCR Processing** is off in **Settings → File Management**: the file is saved and the sticker's details are left as they are.

**Cause**: Low-quality scan, handwriting, or a language other than English

**Fix**:
- Re-scan at 300 DPI or higher
- Ensure document is well-lit, flat, and in focus
- OCR reads typed English text, not handwriting

See [Documents - OCR](Documents.md#ocr).

### File upload fails

**Possible Causes**:
- File too large: by default over 10 MB for photos and attachments, over 25 MB for documents. **Settings → File Management** shows the limits in force; see [Upload Limits](Installation.md#upload-limits)
- Browser timeout on slow connection
- Disk full on server

**Fix**:
- Compress large files before uploading
- Check server disk space: `df -h`
- Increase Docker timeout if needed

---

## Privacy & Data Questions

### Does MyGarage send my data anywhere?

Your records stay on your server. MyGarage calls outside services only for features that need them:
- NHTSA: VIN decoding (the VIN), and recalls and service bulletins (make, model and year)
- data.economie.gouv.fr (France only): RappelConso recalls (make, model and dates) and pump prices near a saved station
- POI Finder: your search location goes to the search provider, and a typed address to OpenStreetMap
- WiCAN firmware checks: GitHub
- Notification services, the Telegram bot, and any LLM endpoint you set up

### Does MyGarage record my location?

Only if you connect a **Torque Pro** source. Torque can send GPS coordinates
alongside its OBD2 readings, and MyGarage stores those as trip routes and a
last-known-location card. This arrived in v3.0.0.

**WiCAN devices do not report position**, so a WiCAN-only setup records no
location data at all.

Location tracking is **on by default** for each vehicle, though it does nothing
until a Torque source is actually sending GPS. To switch it off, open the
vehicle's **LiveLink → Trips** tab and turn off **Location tracking**. It's
per-vehicle, so each one is set independently.

Points already recorded are kept for **90 days by default** and then pruned
automatically, on the same retention setting as raw telemetry (adjustable in
LiveLink settings). There's no on-demand delete button — shortening the retention
window is how you clear history sooner.

As with everything else, location data stays on your server. See
[Trips & Location](LiveLink#trips--location-torque-only) for the full picture.

### Can I disable VIN decoding?

VIN decoding is optional. You can always use manual entry instead of VIN decoding.

### Does MyGarage require internet access?

**Optional**. MyGarage works offline except for:
- VIN decoding and recall checks (NHTSA, or RappelConso in France)
- POI Finder searches
- Notifications and Telegram fuel commands (require access to those services)
- OIDC authentication (requires identity provider access)

All core features (service tracking, fuel logging, document storage) work offline.

### Can I use MyGarage on a private network (no internet)?

Yes. Install MyGarage on your local network, and access it via local IP address. The features listed above won't work without internet, but all other features will. Telegram fuel commands need only outbound access to Telegram, not a public address.

### Is MyGarage GDPR compliant?

MyGarage is a self-hosted tool, so **you** are the data controller (not us). As long as you:
- Use it for personal/family data only (or get user consent for business use)
- Implement proper security (auth, HTTPS)
- Provide data export/deletion capabilities (built-in)

...you should be GDPR compliant. Consult a lawyer if using for business purposes.

---

## Customization & Development

### Can I customize the MyGarage interface?

MyGarage includes a light/dark theme toggle in the top bar, and an accent colour
picker offering six colours (blue, amber, teal, red, violet, green) under the
gear icon → **Quick settings**. Both save to your account, so the choice follows
you between devices. **Quick settings** also holds your units, time format,
language, currency and dashboard order. Customization beyond that requires modifying the source code.

### Can I contribute to MyGarage?

Yes! MyGarage is open-source. See [CONTRIBUTING.md](https://github.com/homelabforge/mygarage/blob/main/CONTRIBUTING.md) for development setup and contribution guidelines.

### Can I request features?

Yes! Open a [Feature Request](https://github.com/homelabforge/mygarage/issues/new/choose) on GitHub or discuss in [GitHub Discussions](https://github.com/homelabforge/mygarage/discussions).

### Can I hire you to add custom features?

The MyGarage project is community-driven and doesn't offer paid custom development. However, you can:
- Fork the project and customize yourself (MIT License allows this)
- Hire a developer familiar with Python/React to customize
- Submit feature requests for community implementation

---

## Licensing & Legal

### What license does MyGarage use?

**MIT License** - Very permissive open-source license.

You can:
- ✅ Use commercially
- ✅ Modify the code
- ✅ Distribute modified versions
- ✅ Use privately

You must:
- Include the original license and copyright notice

You cannot:
- ❌ Hold the authors liable

### Can I sell MyGarage as a service (SaaS)?

Yes. The MIT License allows commercial use. You can host MyGarage and charge users for access.

**However**: You must include the MIT License notice and give credit to the original project.

### Can I rebrand MyGarage for my business?

Yes, but you must retain the MIT License notice in the codebase (users have the right to know it's based on MyGarage).

---

## Support & Community

### Where can I get help?

1. **Documentation** - Read the [wiki](https://github.com/homelabforge/mygarage/wiki) (you're here!)
2. **Troubleshooting Guide** - See [Troubleshooting](Troubleshooting)
3. **GitHub Discussions** - Ask questions at [GitHub Discussions](https://github.com/homelabforge/mygarage/discussions)
4. **GitHub Issues** - Report bugs at [GitHub Issues](https://github.com/homelabforge/mygarage/issues)

### How do I report a bug?

1. Check if it's already reported: [Search Issues](https://github.com/homelabforge/mygarage/issues)
2. If not, open a new issue: [Bug Report](https://github.com/homelabforge/mygarage/issues/new/choose)
3. Include:
   - MyGarage version (`docker inspect mygarage | grep "org.opencontainers.image.version"`)
   - Steps to reproduce
   - Expected vs actual behavior
   - Relevant logs (`docker logs mygarage`)

### How do I report a security vulnerability?

**Do NOT open a public issue!**

Use [GitHub Security Advisories](https://github.com/homelabforge/mygarage/security/advisories/new) or create a private issue. See [SECURITY.md](https://github.com/homelabforge/mygarage/blob/main/SECURITY.md).

### Is there a Discord/Slack community?

Yes, the [HomelabForge Discord](https://discord.gg/YG2vV32NBg). [GitHub Discussions](https://github.com/homelabforge/mygarage/discussions) works too.

---

## Future Features

### Does MyGarage support OBD-II integration?

**Yes!** MyGarage now includes **LiveLink**, which integrates with WiCAN OBD2 devices for real-time telemetry. See the [LiveLink Guide](LiveLink) for details.

### Does MyGarage support vehicle telematics?

**Yes, via LiveLink.** MyGarage supports real-time telemetry monitoring through WiCAN devices and the Torque Pro app:
- ✅ Live engine data (RPM, speed, temperatures)
- ✅ Drive session tracking
- ✅ Diagnostic trouble codes (DTCs)
- ✅ Automatic odometer sync
- ✅ GPS trips and last known location — **Torque Pro sources only**, and switchable per vehicle. WiCAN devices don't report position. See [Trips & Location](LiveLink#trips--location-torque-only).

**Not supported:**
- ❌ Remote vehicle control

> **Changed in v3.0.0.** Earlier versions of this page said GPS tracking was not
> supported. That is no longer accurate — GPS trips arrived in v3.0.0 for Torque
> sources. See [Does MyGarage record my location?](#does-mygarage-record-my-location)
> for what is stored and how to switch it off.

---

## Still Have Questions?

- **Search Discussions**: [GitHub Discussions](https://github.com/homelabforge/mygarage/discussions)
- **Ask the Community**: [Post a Question](https://github.com/homelabforge/mygarage/discussions/new?category=q-a)
- **Read Troubleshooting**: [Troubleshooting Guide](Troubleshooting)

---

**Next**: Check the [Troubleshooting Guide](Troubleshooting) for detailed problem-solving steps.