# 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 commercial fleet?

Yes. The MIT License allows commercial use. MyGarage scales to support dozens of vehicles and users.

### Is my data safe and private?

Yes. MyGarage is self-hosted - **all data stays on your server**. Nothing is sent to external services except:
- VIN decoding (NHTSA public API - no personal data sent)
- OCR processing (local, not cloud-based)
- Email notifications (if you configure SMTP)

### 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.3+.

### 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 → Authentication** and switch to **Local** (username/password) or **OIDC**. The change takes effect immediately — no restart or environment variables. In Local mode, register the first account from the login screen.

### 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 → Users

**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#oidc-sso-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 **Settings → System → Units** 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. 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.

One exception: the **window sticker** MSRP fields don't yet handle a *typed*
comma decimal. Pasted and scanned values are fine. See
[Troubleshooting](Troubleshooting#window-sticker-msrp-reads-the-wrong-amount).

### 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 (Fuelly, Car Minder, etc.)?

Yes. Export your data as CSV, then import via:
- Settings → Import Data → Upload CSV

Map columns during import (date, odometer, cost, etc.).

### 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.

### Can I export my data?

Yes. Settings → Export Data supports:
- **JSON** - Complete data backup
- **CSV** - Service records and fuel logs
- **PDF** - Visual reports with charts

---

## LiveLink & Telemetry

### What is LiveLink?

LiveLink is MyGarage's real-time vehicle telemetry integration. It connects WiCAN OBD2 devices to MyGarage, 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?

You need a **WiCAN** device from [MeatPi Electronics](https://www.meatpi.com/products/wican):

| 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?

No. LiveLink specifically integrates with **WiCAN devices** that can push data via HTTPS POST or MQTT. Generic Bluetooth OBD2 scanners (like ELM327) are not supported.

### 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 use both simultaneously — LiveLink deduplicates data automatically.

### 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) in Settings → LiveLink 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"?

Phantom devices appear when using MQTT with retained messages. If other WiCAN devices previously published to your broker, their retained messages may be replayed when MyGarage subscribes.

**Solution:** Clear retained messages from your MQTT broker. 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 respective vehicle in Settings → LiveLink → Devices.

---

## 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?

Yes! See [Database Configuration - Migration](Database-Configuration.md#migrating-from-sqlite-to-postgresql).

TL;DR: Export data as JSON, switch database, import JSON.

### How do I backup my data?

Easiest: **Settings → Backup & Restore** (works for both databases; SQLite backups use the Online Backup API, so they're safe while the app is running).

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
docker exec mygarage sqlite3 /data/mygarage.db "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?" 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).

### OCR not extracting text from documents

**Cause**: Low-quality scan or unsupported language

**Fix**:
- Re-scan at 300 DPI or higher
- Ensure document is well-lit, flat, and in focus
- OCR works best on typed documents (not handwritten)

See [Documents - OCR Text Extraction](Documents.md#ocr-text-extraction).

### File upload fails

**Possible Causes**:
- File too large (> 10MB for photos, > 25MB for PDFs)
- 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?

No. All data stays on your server. The only external API call is VIN decoding (NHTSA), which sends only the VIN (no personal info).

### 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 (requires NHTSA API access)
- Email notifications (requires SMTP server access)
- 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. VIN decoding won't work, but all other features will.

### 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. 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?

No. Use [GitHub Discussions](https://github.com/homelabforge/mygarage/discussions) for community interaction.

---

## Future Features

### Will MyGarage support mobile apps (iOS/Android)?

It's on the roadmap! For now, use the mobile-optimized web interface.

### 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.