sori.studio/deadman-switch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f7ee8cb9237864e915b1024d96e8a9055e544a87
deadman-switch/docs/DEPLOY.md
zenn f7ee8cb923 초기 버전 v1.0.0 구현 
개인 NAS용 생존 확인 웹앱의 기본 기능, Docker 배포 설정, 설치 문서를 추가합니다.
2026-06-10 11:48:06 +09:00

6.9 KiB
Raw Blame History

Collection Keeper 설치 가이드

이 문서는 컴퓨터를 잘 모르는 분도 따라할 수 있도록 작성했습니다.

프로젝트 폴더를 USB로 통째로 옮기지 않아도 됩니다.
Git 저장소에서 받아서 설치하는 방식을 권장합니다.

  • 저장소 주소: https://git.sori.studio/zenn/collection.sori.studio.git
  • 현재 버전: v1.0.0

1. 이 프로그램이 하는 일

Collection Keeper는 웹페이지에 들어와서 가끔 클릭해 주는 작은 서비스입니다.

  • 클릭하면 "아직 살아있음" 기록이 남습니다.
  • 일정 기간 동안 아무도 클릭하지 않으면, 미리 준비한 스크립트가 실행됩니다.
  • NAS에서는 /home/zenn/Collection 폴더를 삭제하도록 설정되어 있습니다.

중요:

  • 웹앱이 직접 폴더를 지우지 않습니다.
  • 실제 삭제는 scripts/cleanup.sh가 담당합니다.

2. 준비물

개발 서버(맥/PC에서 먼저 테스트)

  • Node.js 20 이상
  • npm
  • Git

상용 서버(NAS)

  • Docker
  • Docker Compose
  • Git
  • NAS에 /home/zenn/Collection 폴더

3. Git이란?

Git은 프로그램 소스를 인터넷 저장소에 올려두고, 서버에서 내려받는 도구입니다.

폴더를 직접 복사하는 것보다 좋은 점:

  • 나중에 업데이트가 쉽습니다.
  • 어떤 버전을 썼는지 관리할 수 있습니다.
  • 여러 서버에 같은 방식으로 설치할 수 있습니다.

4. 개발 서버 설치 (맥/PC)

4-1. Git 설치 확인

터미널을 열고 아래를 입력합니다.

git --version

버전이 나오면 설치되어 있는 것입니다.

4-2. 프로젝트 받기

원하는 폴더로 이동한 뒤 아래를 실행합니다.

cd ~/Desktop
git clone https://git.sori.studio/zenn/collection.sori.studio.git
cd collection.sori.studio

4-3. 패키지 설치

npm install

4-4. 실행

npm start

브라우저에서 접속:

http://localhost:40100

아래 명령으로 버전 정보가 나오면 정상입니다.

curl http://localhost:40100/api/version

4-5. 개발 중 자동 재시작

npm run dev

5. 상용 서버 설치 (NAS + Docker)

NAS에서는 보통 SSH로 접속해서 명령어를 실행합니다.

5-1. NAS에 접속

예시:

ssh zenn@NAS_IP

NAS_IP는 NAS의 실제 IP 주소로 바꿉니다.

5-2. 설치 폴더 만들기

mkdir -p /home/zenn/docker
cd /home/zenn/docker

5-3. Git으로 프로젝트 받기

git clone https://git.sori.studio/zenn/collection.sori.studio.git
cd collection.sori.studio

5-4. 삭제 대상 폴더 확인

기본 삭제 경로:

/home/zenn/Collection

이 폴더가 실제로 존재하는지 확인합니다.

ls -ld /home/zenn/Collection

5-5. 삭제 스크립트 확인

cat scripts/cleanup.sh
chmod +x scripts/*.sh

5-6. 설정 확인

기본 설정 파일:

config/default.json

자주 바꾸는 값:

설정 기본값 설명
threshold_days 90 며칠 동안 클릭이 없으면 스크립트 실행
cooldown_seconds 1 클릭 인정 최소 간격
collection_path /home/zenn/Collection 삭제 대상 폴더
trigger_script ./scripts/cleanup.sh 실행할 스크립트
port 40100 웹 접속 포트

Docker에서는 docker-compose.yml도 함께 확인합니다.

5-7. Docker 실행

docker compose up -d --build

5-8. 실행 확인

docker compose ps
docker compose logs -f collection-keeper

브라우저 접속:

http://NAS_IP:40100

6. 설정 항목 전체

6-1. config/default.json

항목 기본값 설명
threshold_days 90 생존 확인 허용 일수
threshold_seconds null 테스트용 초 단위 타이머. 값이 있으면 일수보다 우선
cooldown_seconds 1 클릭 인정 쿨다운
check_interval_seconds 60 스크립트 검사 주기
database_path ./data/keeper.sqlite SQLite 경로
trigger_script ./scripts/cleanup.sh 만료 시 실행 스크립트
background random 배경 이미지 설정
collection_path /home/zenn/Collection Collection 폴더
port 40100 웹 포트
recent_traces_limit 5 최근 흔적 개수
reset_token "" 초기화 API 보호 토큰

6-2. 화면 문구 (public/custom.js)

항목 설명
keeperTextLines 오른쪽 아래 안내 문구
farewellTextLines 만료 후 중앙 작별 문구
emojis 클릭 이모지 목록
clickMessages 클릭 시 나오는 문장 목록

코드를 몰라도 이 파일의 따옴표 안 문장만 바꾸면 됩니다.

6-3. Docker 환경 변수

docker-compose.yml에서 바꿀 수 있습니다.

  • THRESHOLD_DAYS
  • THRESHOLD_SECONDS
  • COOLDOWN_SECONDS
  • CHECK_INTERVAL_SECONDS
  • PORT
  • DATABASE_PATH
  • TRIGGER_SCRIPT
  • COLLECTION_PATH
  • BACKGROUND
  • RESET_TOKEN

7. 업데이트 방법

이미 설치한 서버에서 새 버전을 받을 때:

cd /home/zenn/docker/collection.sori.studio
git pull
docker compose down
docker compose up -d --build

개발 서버:

cd collection.sori.studio
git pull
npm install
npm start

8. 테스트 방법

8-1. 짧은 타이머 테스트

10초 후 만료를 보고 싶다면:

THRESHOLD_SECONDS=10 npm start

Docker:

THRESHOLD_SECONDS: 10

8-2. 초기화

curl -X POST http://localhost:40100/api/reset

토큰을 켠 경우:

curl -X POST http://localhost:40100/api/reset \
  -H 'Content-Type: application/json' \
  -d '{"token":"내-토큰"}'

주의:

  • 삭제 테스트 전에는 반드시 백업하세요.
  • cleanup.sh는 실제로 /home/zenn/Collection을 삭제합니다.

9. 자주 쓰는 명령어

Docker

docker compose up -d --build
docker compose ps
docker compose logs -f
docker compose restart
docker compose down

Git

git clone https://git.sori.studio/zenn/collection.sori.studio.git
git pull
git status

10. 문제 해결

포트가 이미 사용 중

lsof -nP -iTCP:40100 -sTCP:LISTEN

화면은 뜨는데 삭제가 안 됨

  1. threshold_days 또는 threshold_seconds 확인
  2. docker compose logs -f에서 [keeper] Threshold exceeded 확인
  3. scripts/cleanup.sh 실행 권한 확인
  4. /home/zenn/Collection 볼륨 마운트 확인

버전 확인

API로 확인합니다.

curl http://localhost:40100/api/version

11. 폴더를 통째로 옮겨도 되나?

가능은 하지만 권장하지 않습니다.

권장 방식:

git clone https://git.sori.studio/zenn/collection.sori.studio.git

이 방식이 업데이트와 버전 관리에 훨씬 유리합니다.

Reference in New Issue View Git Blame Copy Permalink