Docker로 Berth 설치하기

준비물

• Compose가 포함된 Docker, 또는 컨테이너 이미지를 실행할 수 있는 NAS(Synology, Unraid, CasaOS).
• amd64 또는 arm64 기기 — Raspberry Pi나 ARM NAS도 돼요.
• ./data용 로컬 디스크의 폴더. 네트워크 공유(NFS, SMB)에는 두지 마세요. 그곳에서는 SQLite가 데이터베이스를 손상시킬 수 있어요.

Docker Compose로 실행

./data에는 데이터베이스와 백업, 로컬 저장소, secret.key가 들어 있어요.

mkdir berth && cd berth
curl -fsSLO https://raw.githubusercontent.com/joveptesg/berth/main/docker-compose.yml
docker compose up -d              # http://localhost:8080, data in ./data
docker compose logs berth         # the setup code is in the log

secret.key의 사본은 백업과 따로 보관하세요. 이 파일이 없으면 데이터베이스에 있는 저장소 키를 읽을 수 없어요.

브라우저에서 처음 설정하기

1. 브라우저에서 서버 주소를 여세요: http://<server>:8080 또는 호스팅에서 할당한 도메인.
2. 로그의 server is not set up: … enter the setup code K7P2-9QXM 줄에서 설정 코드를 찾으세요. 설정을 마칠 때까지 재시작할 때마다 코드가 바뀌어요.
3. 코드를 입력하고 관리자를 만드세요. 지금 연 주소가 휴대폰 QR 코드의 홈 네트워크 주소 또는 인터넷 주소가 돼요. 나중에 설정 → 서버에서 바꿀 수 있어요.
4. 첫 책을 업로드하세요: 폴더나 파일을 관리자로 끌어다 놓으면 Berth가 태그, 챕터, 표지를 읽어요. 확인한 뒤 책을 라이브러리에 추가하세요.

일반 Docker, NAS, Raspberry Pi

일반 Docker를 쓰거나 NAS 화면에서 이미지 이름을 물어볼 때:

• NAS 화면(Synology Container Manager, Unraid, CasaOS)에서는 이미지 ghcr.io/joveptesg/berth:1, 포트 8080, /data에 마운트할 폴더를 지정하세요.
• Raspberry Pi에서도 같은 명령어가 작동해요. arm64 이미지를 자동으로 받아요.

docker run -d --name berth --restart unless-stopped \
  -p 8080:8080 -v "$PWD/data:/data" ghcr.io/joveptesg/berth:1
docker logs berth                 # the setup code is in the log

업데이트와 롤백

1 태그는 모든 1.x 릴리스를 따라가고, 1.0은 1.0의 수정 버전을 따라가며, 1.0.1 같은 정확한 태그는 절대 바뀌지 않아요. Watchtower 같은 자동 업데이트 도구에는 latest를 쓰지 마세요. 새 메이저 버전까지 따라가요.

새 버전은 데이터베이스 스키마를 바꾸기 전에 사본을 ./data/backups에 저장해요(최근 3개 보관). 롤백하려면 docker-compose.yml에서 이전 버전을 고정하고 그 사본을 복원하세요:

1. docker compose stop berth
2. docker compose run --rm berth admin restore /data/backups/auto-<time>.sqlite
3. docker compose up -d

docker compose pull && docker compose up -d

인터넷에서 접속하기

Berth는 일반 HTTP로 동작하며, 집에서는 그걸로 충분해요. 외부에서 접속하려면 앞단에 HTTPS 리버스 프록시를 두세요. 예를 들어 Caddy는 이렇게 해요:

books.example.com {
	reverse_proxy localhost:8080
}

그다음 관리자의 설정 → 인터넷 주소에 https://books.example.com을 입력하면 휴대폰용 QR 코드에 포함돼요. 앱은 홈 네트워크 주소와 인터넷 주소를 알아서 전환해요.

백업

• 관리자의 설정 → 백업에서 데이터베이스 사본을 내려받거나, 자동 백업이나 업로드한 파일로 복원할 수 있어요. 복원 전에 현재 데이터베이스를 먼저 저장하므로 복원을 되돌릴 수 있어요.
• S3 저장소를 쓰면 서버가 매일 데이터베이스 사본을 버킷에도 넣어 둘 수 있어요. 데이터베이스가 있는 디스크와는 떨어진 곳이에요.
• 콘솔에서(서버를 멈춘 상태로): berth admin restore <file>.

자주 묻는 질문