모두를 위한 오픈소스 자산 관리 인프라

Shelf는 장비, 기기, 도구, 차량, 소품, 재고 등 물리적 자산을 추적하는 플랫폼입니다. 팀이 자신이 무엇을 가지고 있는지, 어디에 있는지, 누가 사용하고 있는지 알아야 할 때 이를 위해 구축되었습니다. 조직은 Shelf를 사용하여 위치별로 수천 개의 자산을 관리하며, 팀원들에게 역할 기반 접근(role-based access)을 제공합니다.

기능

• QR 자산 태그(QR asset tags) — QR 코드를 생성하고 인쇄합니다. 어떤 휴대폰으로든 스캔하여 자산을 확인하거나, 대여하거나, 보고할 수 있습니다.
• 예약 및 예약 관리(Bookings and reservations) — 장비를 예약하고 이중 예약을 방지하며, 캘린더 통합 기능을 사용하여 체크아웃/반납 날짜를 설정합니다.
• 보관 추적(Custody tracking) — 자산을 팀원에게 할당합니다. 언제 누가 무엇을 가지고 있는지 알 수 있습니다.
• 위치 관리(Location management) — 계층적 위치(건물, 층, 방, 선반)를 지원합니다. GPS 태그 지정도 가능합니다.
• 팀 역할(Team roles) — 소유자(Owner), 관리자(Admin), 기본(Base), 셀프 서비스(Self Service) 역할을 통해 세분화된 권한을 설정할 수 있습니다.
• 사용자 정의 필드(Custom fields) — 자산에 구매 날짜, 보증 정보, 일련 번호, 상태 등 모든 메타데이터를 추가할 수 있습니다.
• 카테고리 및 태그(Categories and tags) — 자산을 카테고리로 정리합니다. 유연한 교차 그룹화를 위해 태그를 사용합니다.
• 키트(Kits) — 여러 자산들을 키트로 묶어(예: 노트북 + 충전기 + 도킹 스테이션) 하나의 단위로 관리할 수 있습니다.
• 검색 및 필터링(Search and filtering) — 고급 필터를 갖춘 전체 텍스트 검색을 지원합니다. 저장된 필터 프리셋도 제공됩니다.
• CSV 가져오기/내보내기(CSV import/export) — 스프레드시트에서 자산을 일괄 가져올 수 있습니다. 보고서 작성을 위해 내보낼 수도 있습니다.
• 자산 알림(Asset reminders) — 유지 보수, 교정, 보증 만료에 대한 경고를 예약할 수 있습니다.
• 감사 추적(Audit trail) — 모든 자산에 대한 메모 및 활동 로그가 기록됩니다.
• 다중 워크스페이스(Multi-workspace) — 다른 조직이나 부서의 별도 재고를 관리할 수 있습니다.
• 스캐너(Scanner) — 내장된 QR/바코드 스캐너와 함께 대량 작업 기능(보관 할당, 위치 업데이트, 예약 추가)을 제공합니다.

기술 스택 (Tech Stack)

시작하기 (Getting Started)

전제 조건 (Prerequisites)

• Node.js >= 22.20.0
• pnpm >= 9.15.4
• Supabase 프로젝트 (무료 티어 사용 가능)

설정 (Setup)

# 레포지토리 클론하기
git clone https://github.com/Shelf-nu/shelf.nu.git
cd shelf.nu
...

.env 파일을 열어 Supabase 자격 증명 및 기타 설정을 구성하세요. 단계별 지침은 Supabase 설정 가이드를 참조하세요.

# Prisma 클라이언트 생성 및 마이그레이션 실행
pnpm webapp:setup

...

앱은 https://localhost:3000에서 실행됩니다 (개발 서버는 기본적으로 로컬 인증서로 HTTPS를 사용합니다).

SSL 인증서 및 문제 해결을 포함한 자세한 설정 지침은 로컬 개발 가이드를 참조하세요.

프로젝트 구조

shelf.nu/
├── apps/
│   ├── webapp/          # 메인 애플리케이션 (React Router + Hono)
...

이 모노레포는 pnpm workspaces와 Turborepo로 관리됩니다. @shelf/database 패키지가 모든 데이터베이스 관련 사항(스키마, 마이그레이션 및 Prisma 클라이언트 생성)을 담당합니다.

명령어

배포

Fly.io

Shelf는 CI/CD를 위해 GitHub Actions와 함께 Fly.io에 배포됩니다. dev로 푸시하면 스테이징 배포가 트리거되고, main으로 푸시하면 프로덕션 배포가 트리거됩니다. 두 경우 모두 lint, typecheck, test, Docker build 및 배포를 실행합니다.

전체 설정 지침은 배포 가이드를 참조하세요.

Docker

커뮤니티에서 유지 관리하는 Docker 지원을 통해 자체 호스팅이 가능합니다. 외부 Supabase 인스턴스가 필요합니다.

Docker 가이드를 참조하세요.

문서

기여 (Contributing)

기여를 환영합니다. 기여 가이드라인을 확인하고, "Open for contributions" 레이블이 지정된 이슈를 찾아보세요.

본 프로젝트는 commitlint에 의해 강제되는 conventional commits 방식을 사용합니다. pre-commit hook은 Lefthook을 통해 ESLint, Prettier, TypeScript 검사를 실행합니다.

질문이 있거나 기여에 대해 논의하고 싶다면 Discord에 참여하세요.

라이선스 (License)

Shelf.nu는 예외가 하나 있는 AGPL-3.0 라이선스를 따릅니다.

apps/companion/의 보조 모바일 앱은 오픈 소스가 아닙니다. 해당 소스는 PolyForm 내부 사용 라이선스 1.0.0에 따라 제공됩니다. 귀사 자체의 내부 비즈니스 운영을 위해 이를 읽고, 빌드하고, 변경할 수 있습니다. 하지만 배포할 수는 없습니다. 이 앱 또는 이 앱을 기반으로 한 앱을 Apple App Store, Google Play 또는 기타 스토어에 게시하는 것은 배포로 간주됩니다.

이 섹션은 요약본입니다. 라이선스 파일이 구속력 있는 약관입니다.