가족·홈랩용 셀프호스팅 차량 관리 — 정비 스케줄, 주유 기록, 알림, OBD/GPS 주행, Home Assistant 연동(선택).
최신 릴리스는 GitHub Releases에서 확인하세요.
문서: docs/ARCHITECTURE.md · docs/INTEGRATIONS.md · docs/PROGRESS.md
- 차량·사용자·차량별 접근 ACL (관리자 / 일반)
- 모바일 우선의 고정형 하단 네비게이션 바로 한 손 조작 편의성 극대화
- 스마트 홈 리다이렉트: 계정에 등록된 차량이 1대뿐인 경우 차량 목록 대시보드를 건너뛰고 바로 차량 개요로 진입
- 정비 + 행정·법정 스케줄, 거리·시간 이중 알림
- 연료 타입별 정비 프리셋, 전역 행정·법정 프리셋
- 주유 기록·영수증 첨부, 오피넷 주변 주유소(선택)
- 전기차 충전소 찾기(한국환경공단 API, 선택) — 주유소와 마찬가지로 거리순/가격순 검색, 지도에 번호 마커로 표시
- OBD 수집(Torque Pro), REST/WebSocket 텔레메트리, 자동 트립 분할
- 현대 블루링크 커넥티드카 연동(베타, 국내 전용) — OBD 동글 없이 실제 주행거리·주행가능거리·경고등 조회, 오도미터 자동 동기화. 가족 구성원 각자 프로필에서 본인 계정 연동
- 주행 리포트, 경로 지도 (OSM / 카카오 / 네이버 / T맵) 및 진행 방향 화살표, 주행 개별 메모 추가/편집 및 역지오코딩
- 대시보드 알림 배지 및 차량 요약 카드 (최근 주유 비용 포함)
- 차량별 관리 레벨·뱃지(게이미피케이션) 전용 화면
- 네비게이션 구조 단일화 (상단 헤더 제거 및 버전 표시 더보기 시트 이동)
- 관리자 백업/복원, PWA, 한/영 i18n
- 사용자 없을 때 최초 관리자 부트스트랩
로그인 후 홈 화면입니다. 차량이 여러 대인 경우에는 통합 대시보드가 표시되어 모바일에 최적화된 화면에서 각 차량 카드별 현재 주행거리, 최근 주행 거리, 최근 주유 비용, 지남/임박 알림 건수를 한눈에 볼 수 있습니다. 하단 네비게이션 바를 통해 홈, 빠른 입력, 설정으로 바로 이동할 수 있습니다.
차량별 허브입니다. 최근 지출 요약 카드, 월간 비용 차트, 마지막 주행 정보 및 지도가 제공됩니다. 전기차 화면은 충전 상태와 배터리 관련 정보를 표시하며 주변 충전소 찾기가 연동되고, 내연차 화면은 연료 게이지와 오피넷 기반 주변 주유소 찾기 연동을 제공합니다.
어디서나 주유/충전 및 정비를 바로 기록하는 화면입니다. 전기차는 충전 전력량(kWh) 입력, kWh당 단가, 충전소 검색을 지원하며, 내연차는 정유사 브랜드 로고 선택(오피넷), 주유량(L), 리터당 단가 입력을 지원합니다.
거리 및 시간 기준 정비 스케줄과 행정 알림을 관리합니다. 엔진오일/오일필터 교체 주기(내연차 전용) 등 차종에 최적화된 정비 프리셋이 기본 적용됩니다.
주행 리포트, 충전/주유 로그, 정비 이력을 한곳에 모아 보여줍니다. 내연차는 풀탱크 기준 주유 연비(km/L)가 자동 계산되고, 전기차는 에너지 소모량 지표를 중심으로 내역을 표시합니다.
주유/충전 및 정비를 꾸준히 기록해 경험치를 모으고 차량 레벨을 올려 뱃지를 획득하는 화면입니다.
차량 등록/관리, 사용자 추가/수정, 연료타입별 정비 프리셋 설정, 지도/날씨/알림 API 연동, 백업/복원, 그리고 개인 프로필 변경 등 모든 관리용 설정 기능을 하단 네비게이션 시트에서 간편하게 사용할 수 있습니다.
Proxmox (권장)
bash -c "$(curl -fsSL https://raw.githubusercontent.com/eigger/garage/master/proxmox/ct/garage.sh)"완료 후 브라우저에서 http://<LXC_IP> 로 접속합니다.
Docker Compose
docker compose -f docker-compose.prod.yml up -d시작 전에 .env에 POSTGRES_PASSWORD, JWT_SECRET을 설정하세요.
신규 설치 시 사용자가 없으면 /login에 최초 관리자 생성이 표시됩니다.
/login열기- 이름·이메일·비밀번호 입력
- 제출 →
ADMIN으로 로그인됨
공개 회원가입은 없습니다. 이후 계정은 관리자가 사용자 관리에서만 만듭니다.
- 하단 네비게이션 바 더보기 시트 → 차량 관리
- 이름, 번호판, 제조사/모델/연식, 연료 타입 입력
- 저장
해당 연료 타입 정비 프리셋과 행정·법정 스케줄(검사, 보험, 세금 등)이 자동으로 복사됩니다. 기본값은 더보기 시트 아래의 정비 마스터 프리셋 관리에서 수정합니다.
| 할 일 | 위치 |
|---|---|
| 주유 / 정비 기록 | 하단 네비게이션 → 빠른 입력 |
| 주기 수정 | 차량 → 정비 스케줄 |
| 이력·연비·주행 | 차량 → 내역 |
| OBD / Torque / REST 토큰 | 차량 → 톱니바퀴 → OBD & GPS |
| 가족 계정 | 하단 네비게이션 더보기 시트 → 사용자 관리 |
| 오피넷 / 지도 API 키 | 하단 네비게이션 더보기 시트 → API 연동 관리 |
| 백업 / 복원 | 하단 네비게이션 더보기 시트 → 백업/복원 |
Home Assistant는 hass-garage 커스텀 통합구성요소(HACS)로 YAML 편집 없이 화면에서 바로 연동할 수 있습니다 — 위치/RPM/속도/연료/주행거리를 자동 전송하고, Garage가 계산한 마지막 위치·리마인더를 센서로 받아옵니다.
YAML로 직접 붙이고 싶다면 아래처럼 차량 apiToken으로 텔레메트리를 전송할 수도 있습니다(로그인 JWT 아님).
POST /api/ingest/telemetry
Authorization: Bearer <apiToken>
Content-Type: application/json
{ "speed": 65, "lat": 37.56, "lon": 126.97, "odometer": 45230, "inVehicle": true }apiToken 자체가 차량을 특정하므로 URL에 별도 vehicleId가 필요 없습니다.
주유·정비 기록 API는 docs/INTEGRATIONS.md를 참고하세요.
수집 URL·토큰은 차량 → OBD & GPS에서 복사합니다.
garage/
apps/
api/ # Fastify + Prisma
web/ # Next.js App Router (PWA, 한/영)
packages/
shared/ # 공유 Zod 스키마 / 카탈로그
docker-compose.yml / docker-compose.prod.yml
Caddyfile
proxmox/ # LXC 원클릭 설치
npm install
cp .env.example .env # POSTGRES_PASSWORD, JWT_SECRET 설정
docker compose up -d postgres
npm run prisma:migrate
npm run seed -w apps/api # 부트스트랩 UI 대신 시드 관리자를 쓸 때
npm run dev:api # :8080
npm run dev:web # :3000http://localhost:3000/login 으로 접속합니다.
유용한 스크립트: npm run build, npm run test, npm run prisma:generate.
- 구성: PostgreSQL 16 + API + Web + Caddy (
:80) - 프로덕션 compose에서 API 기동 시
prisma migrate deploy실행 - 이미지:
ghcr.io/<owner>/garage-api/garage-web(latest+ semver) - LXC 업데이트: 컨테이너에서
update(compose 이미지 pull)
| 워크플로 | 트리거 | 목적 |
|---|---|---|
.github/workflows/ci.yml |
master Push / PR |
설치·빌드·테스트 |
.github/workflows/docker-release.yml |
GitHub Release | GHCR 이미지 푸시 |
MIT. LICENSE 참고.