Homebox Docker 설치 가이드: 가정용 자산/물품 인벤토리 관리 시스템 ⋆ Blog * JackerLab

개요

Homebox는 가정 사용자를 위해 설계된 인벤토리 및 자산 관리 시스템입니다. 가구, 전자제품, 보증서, 영수증 등 집안의 모든 물건을 체계적으로 관리할 수 있습니다. 심플하고 빠르며, 단일 Docker 컨테이너로 50MB 미만의 메모리만 사용합니다.

항목	내용
GitHub	https://github.com/sysadminsmedia/homebox
공식 문서	https://homebox.software
데모	https://demo.homebox.software
라이선스	AGPL-3.0
GitHub Stars	4.7K+

Homebox란?

왜 Homebox인가?

화재, 홍수, 도난 등의 사고가 발생했을 때 보험 청구를 위해 자산 목록이 필요합니다. 또한 “그 보증서 어디 뒀더라?”, “이거 언제 샀지?” 같은 질문에 대한 답을 찾기 위해서도 인벤토리 관리가 필요합니다.

"Snipe-IT는 IT 관리의 표준이지만 너무 복잡하다.
 나는 단순하고 인지적 부담이 적은 것을 원했다."
 - Homebox 개발자

Homebox vs Snipe-IT

구분	Homebox	Snipe-IT
대상	가정 사용자	IT/기업 자산 관리
복잡도	단순	복잡 (기능 풍부)
설정	수 분	수 시간
리소스	<50MB RAM	높음
용도	가구, 전자제품, 보증서	IT 장비, 소모품

핵심 철학

🧘 단순하지만 확장 가능
🚀 Go로 작성, 극도로 빠름
📦 SQLite + 내장 웹 UI, 휴대성
📇 풍부한 조직 기능
📱 반응형 디자인

주요 기능

자산 관리

기능	설명
아이템 생성	이름과 설명만으로 간단히 생성
위치 관리	계층형 위치 (집 / 거실 / TV 선반)
라벨(태그)	다중 라벨로 분류
커스텀 필드	사용자 정의 메타데이터
첨부 파일	이미지, 영수증, 매뉴얼 업로드

보증 및 구매 추적

기능	설명
구매 정보	구매일, 가격, 판매처
보증 정보	보증 기간, 만료일
영수증	영수증 이미지 첨부
유지보수	정기 점검/수리 일정

QR 코드 및 라벨

기능	설명
QR 코드 생성	아이템/위치별 자동 생성
QR 스캐너	모바일로 스캔하여 바로 접근
라벨 생성기	Avery 5260 호환 라벨 인쇄
Asset ID	자동 생성되는 자산 번호

가져오기/내보내기

기능	설명
CSV 가져오기	대량 아이템 등록
CSV 내보내기	백업 및 보험용
Import Ref	중복 방지 및 업데이트
BOM 생성	Bill of Materials TSV

멀티 유저 및 컬렉션

기능	설명
그룹 기반	같은 그룹 내 공유
컬렉션	여러 인벤토리 분리 관리
가족 초대	가족 구성원 추가
권한 관리	기본적인 사용자 관리

알림 및 연동

기능	설명
유지보수 알림	예정된 점검 알림
Shoutrrr 연동	Discord, Slack, Telegram, Email 등
MQTT 지원	홈 오토메이션 연동
API	REST API 제공

대안 비교

기능	Homebox	Snipe-IT	Grocy	Inventree
대상	가정	IT/기업	가정/재고	제조/부품
복잡도	매우 쉬움	복잡	중간	복잡
QR 코드	✅	✅	✅	✅
보증 추적	✅	✅	❌	❌
소모품 추적	❌	✅	✅	✅
유지보수 일정	✅	✅	❌	❌
멀티 유저	✅	✅	✅	✅
리소스 사용	매우 낮음	높음	낮음	중간
설치 난이도	매우 쉬움	어려움	쉬움	중간

선택 가이드

용도	추천
집안 물품/가구/전자제품	Homebox
IT 장비/기업 자산	Snipe-IT
식료품/소모품 재고	Grocy
제조/부품/BOM	Inventree

시스템 요구 사항

항목	요구 사양
CPU	최소 사양
RAM	<50MB (유휴 시)
저장소	데이터 크기에 따라
포트	7745 (기본)

Homebox는 Go로 작성되어 Raspberry Pi에서도 원활하게 실행됩니다.

Docker 설치

방법 1: 기본 설치

# docker-compose.yml
services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    ports:
      - "3100:7745"
    volumes:
      - ./homebox-data:/data
    environment:
      - TZ=Asia/Seoul
      - HBOX_LOG_LEVEL=info
      - HBOX_LOG_FORMAT=text
      - HBOX_WEB_MAX_UPLOAD_SIZE=10

실행:

mkdir -p ~/homebox && cd ~/homebox

# docker-compose.yml 생성 후
docker compose up -d

접속: http://localhost:3100

방법 2: 회원가입 비활성화 (운영용)

# docker-compose.yml
services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    ports:
      - "3100:7745"
    volumes:
      - ./homebox-data:/data
    environment:
      - TZ=Asia/Seoul
      - HBOX_LOG_LEVEL=info
      - HBOX_LOG_FORMAT=text
      - HBOX_WEB_MAX_UPLOAD_SIZE=10
      # 회원가입 비활성화
      - HBOX_OPTIONS_ALLOW_REGISTRATION=false

💡 먼저 회원가입으로 계정을 만든 후 HBOX_OPTIONS_ALLOW_REGISTRATION=false로 변경하세요.

방법 3: Rootless 이미지 (보안 강화)

# docker-compose.yml
services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest-rootless
    container_name: homebox
    restart: unless-stopped
    ports:
      - "3100:7745"
    volumes:
      - ./homebox-data:/data
    environment:
      - TZ=Asia/Seoul
      - HBOX_LOG_LEVEL=info
      - HBOX_LOG_FORMAT=text
      - HBOX_WEB_MAX_UPLOAD_SIZE=10

권한 설정 필요:

mkdir -p ~/homebox/homebox-data
chown 65532:65532 -R ~/homebox/homebox-data

방법 4: Hardened 이미지 (최고 보안)

# docker-compose.yml
services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest-hardened
    container_name: homebox
    restart: unless-stopped
    ports:
      - "3100:7745"
    volumes:
      - ./homebox-data:/data
    environment:
      - TZ=Asia/Seoul
      - HBOX_LOG_LEVEL=info

⚠️ Hardened 이미지는 distroless 기반으로 MQTT 클라이언트가 포함되지 않습니다.

방법 5: 이메일 알림 설정

# docker-compose.yml
services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    ports:
      - "3100:7745"
    volumes:
      - ./homebox-data:/data
    environment:
      - TZ=Asia/Seoul
      - HBOX_LOG_LEVEL=info
      - HBOX_LOG_FORMAT=text
      - HBOX_WEB_MAX_UPLOAD_SIZE=10
      # SMTP 설정
      - HBOX_MAILER_HOST=smtp.gmail.com
      - HBOX_MAILER_PORT=587
      - HBOX_MAILER_USERNAME=your-email@gmail.com
      - HBOX_MAILER_PASSWORD=your-app-password
      - HBOX_MAILER_FROM=your-email@gmail.com

방법 6: Traefik 연동

# docker-compose.yml
services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    volumes:
      - ./homebox-data:/data
    environment:
      - TZ=Asia/Seoul
      - HBOX_LOG_LEVEL=info
      - HBOX_LOG_FORMAT=text
      - HBOX_WEB_MAX_UPLOAD_SIZE=10
      - HBOX_OPTIONS_ALLOW_REGISTRATION=false
    networks:
      - traefik_network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.homebox.rule=Host(`homebox.example.com`)"
      - "traefik.http.routers.homebox.entrypoints=websecure"
      - "traefik.http.routers.homebox.tls.certresolver=letsencrypt"
      - "traefik.http.services.homebox.loadbalancer.server.port=7745"

networks:
  traefik_network:
    external: true

방법 7: MQTT 라벨 프린터 연동

# docker-compose.yml
services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    ports:
      - "3100:7745"
    volumes:
      - ./homebox-data:/data
      - ./labels:/labels
    environment:
      - TZ=Asia/Seoul
      - HBOX_LOG_LEVEL=info
      - HBOX_LOG_FORMAT=text
      - HBOX_WEB_MAX_UPLOAD_SIZE=10
      # 라벨 프린터 설정
      - HBOX_LABEL_MAKER_PRINT_COMMAND=cp {{.FileName}} /labels/label.png

환경 변수

기본 설정

변수	설명	기본값
`TZ`	타임존	`UTC`
`HBOX_MODE`	실행 모드	`production`
`HBOX_LOG_LEVEL`	로그 레벨 (debug/info/warn/error)	`info`
`HBOX_LOG_FORMAT`	로그 형식 (text/json)	`text`

웹 서버

변수	설명	기본값
`HBOX_WEB_PORT`	웹 포트	`7745`
`HBOX_WEB_HOST`	바인딩 호스트	–
`HBOX_WEB_MAX_UPLOAD_SIZE`	최대 업로드 크기 (MB)	`10`

데이터 저장

변수	설명	기본값
`HBOX_STORAGE_DATA`	데이터 디렉토리	`./.data`
`HBOX_STORAGE_SQLITE_URL`	SQLite 경로	`./.data/homebox.db`

기능 옵션

변수	설명	기본값
`HBOX_OPTIONS_ALLOW_REGISTRATION`	회원가입 허용	`true`
`HBOX_OPTIONS_ALLOW_ANALYTICS`	분석 허용	`true`
`HBOX_OPTIONS_AUTO_INCREMENT_ASSET_ID`	Asset ID 자동 증가	`true`

이메일 (SMTP)

변수	설명
`HBOX_MAILER_HOST`	SMTP 서버
`HBOX_MAILER_PORT`	SMTP 포트
`HBOX_MAILER_USERNAME`	사용자명
`HBOX_MAILER_PASSWORD`	비밀번호
`HBOX_MAILER_FROM`	발신자 주소

라벨 프린터

변수	설명
`HBOX_LABEL_MAKER_PRINT_COMMAND`	라벨 인쇄 명령어

초기 설정

1) 계정 생성

URL: http://localhost:3100
→ Register 클릭
→ 이메일, 이름, 비밀번호 입력

2) 회원가입 비활성화 (권장)

계정 생성 후 docker-compose.yml에서:

environment:
  - HBOX_OPTIONS_ALLOW_REGISTRATION=false

docker compose down
docker compose up -d

3) 위치 설정

기본 위치가 제공되지만, 실제 집 구조에 맞게 수정하세요:

집
├── 거실
│   ├── TV 선반
│   └── 소파 옆
├── 안방
│   ├── 옷장
│   └── 서랍장
├── 주방
│   └── 싱크대 아래
└── 창고
    └── 선반 1

4) 라벨 생성

자주 사용할 라벨 예시:

전자제품
가구
보증서 있음
정기 점검 필요
중요
처분 예정

사용 가이드

아이템 추가

웹 UI:

Items → Create Item
이름, 위치 선택
추가 정보 입력 (선택)
- 설명, 수량
- 구매일, 가격
- 보증 정보
- 커스텀 필드
첨부파일 (영수증, 사진)

CSV 대량 가져오기

CSV 형식:

HB.import_ref,HB.name,HB.location,HB.label,HB.description,HB.purchase_price
item-001,삼성 TV 65인치,거실 / TV 선반,전자제품;보증서 있음,2023년 구매,1500000
item-002,LG 냉장고,주방,전자제품,양문형 냉장고,2000000
item-003,이케아 책장,서재,가구,빌리 책장,150000

지원 컬럼:

컬럼	설명
`HB.import_ref`	중복 방지용 고유 ID (권장)
`HB.name`	아이템 이름 (필수)
`HB.location`	위치 (경로: 집 / 거실 / TV 선반)
`HB.label`	라벨 (세미콜론 구분)
`HB.description`	설명
`HB.quantity`	수량
`HB.purchase_price`	구매 가격
`HB.purchase_from`	구매처
`HB.purchase_time`	구매일 (YYYY-MM-DD)
`HB.warranty_expires`	보증 만료일
`HB.field.{필드명}`	커스텀 필드

가져오기: Tools → Import Items → CSV 파일 업로드

QR 코드 활용

QR 코드 생성:

아이템 상세 페이지 → QR 아이콘 클릭
위치/라벨 페이지에서도 생성 가능

라벨 인쇄:

Tools → Label Generator
Avery 5260 형식 지원
Asset ID 기반 대량 생성

모바일 스캔:

스마트폰 카메라로 QR 스캔
바로 해당 아이템 페이지로 이동

유지보수 알림

알림 설정:

Profile → Notifiers → Create
Shoutrrr URL 입력

Shoutrrr URL 예시:

서비스	URL 형식
Discord	`discord://token@webhookid`
Telegram	`telegram://token@telegram?chats=@channel`
Slack	`slack://token@channel`
Email	`smtp://user:pass@host:port/?from=from&to=to`

유지보수 일정:

아이템 → Maintenance → Add Entry
다음 점검일 설정
알림 자동 발송

백업 및 복원

백업

데이터 위치:

./homebox-data/
├── homebox.db      # SQLite 데이터베이스
├── attachments/    # 첨부파일
└── ...

백업 방법:

# 전체 데이터 디렉토리 백업
tar -czvf homebox-backup-$(date +%Y%m%d).tar.gz homebox-data/

# 또는 Docker 볼륨 사용 시
docker run --rm \
  -v homebox-data:/data \
  -v $(pwd):/backup \
  alpine tar czvf /backup/homebox-backup.tar.gz /data

CSV 내보내기

Tools → Export Items → CSV 다운로드

보험 청구 시 유용합니다.

복원

# 백업 해제
tar -xzvf homebox-backup.tar.gz

# 컨테이너 재시작
docker compose up -d

업데이트

cd ~/homebox

# 백업 먼저!
tar -czvf homebox-backup-$(date +%Y%m%d).tar.gz homebox-data/

# 최신 이미지
docker compose pull

# 재시작
docker compose down
docker compose up -d

# 로그 확인
docker compose logs -f homebox

⚠️ 업그레이드 전 반드시 백업하세요. 다운그레이드는 백업 없이 불가능합니다.

트러블슈팅

권한 오류 (Rootless 이미지)

# 데이터 폴더 권한 설정
chown 65532:65532 -R ./homebox-data

업로드 실패

environment:
  # 업로드 크기 증가 (MB)
  - HBOX_WEB_MAX_UPLOAD_SIZE=50

로그인 안 됨

# 로그 확인
docker compose logs homebox | grep -i error

데이터베이스 손상

# SQLite 무결성 검사
docker compose exec homebox sqlite3 /data/homebox.db "PRAGMA integrity_check;"

이미지 태그

태그	설명
`latest`	안정 버전
`latest-rootless`	비root 실행
`latest-hardened`	최고 보안 (distroless)
`nightly`	개발 버전

활용 사례

1. 가정 자산 인벤토리

목적: 보험, 이사, 자산 관리

가구, 전자제품, 귀중품 등록
구매 영수증 첨부
보증서 만료일 추적
보험 청구용 CSV 내보내기

2. 보증서/영수증 관리

목적: 보증 청구, AS 접수

구매일, 가격, 보증 기간 기록
영수증/보증서 스캔 첨부
보증 만료 전 알림
QR 코드로 빠른 검색

3. 창고/수납 관리

목적: 물건 찾기

위치 계층 구조 (창고 / 선반 1 / 박스 A)
QR 라벨 부착
스마트폰으로 스캔하여 내용물 확인

4. 이사 준비

목적: 물건 분류, 처분

“처분 예정” 라벨로 기증/판매 물품 분류
위치별로 짐 정리
새 집 위치 미리 설정

5. 가족 공유

목적: 가족 구성원 모두 접근

그룹으로 가족 초대
누구나 물건 위치 검색 가능
“엄마, OO 어디 있어?”에 즉답

마무리

Homebox는 가정 사용자를 위해 설계된 심플하고 빠른 인벤토리 관리 시스템입니다. 복잡한 IT 자산 관리 도구 대신, 집안 물품을 체계적으로 관리하고 보증서/영수증을 보관하는 데 최적화되어 있습니다.

핵심 장점

장점	설명
단순함	설정 5분, 학습 곡선 없음
가벼움	<50MB RAM, Raspberry Pi 가능
QR 코드	라벨 생성, 모바일 스캔
보증 추적	구매/보증 정보, 알림
CSV 가져오기	대량 등록, 백업
멀티 유저	가족 공유

이런 분께 추천

집안 물품을 체계적으로 관리하고 싶은 분
보증서/영수증을 잃어버리는 분
이사를 준비하는 분
보험 청구용 자산 목록이 필요한 분
"이거 어디 뒀더라?"를 자주 묻는 분
Snipe-IT가 너무 복잡한 분

개요