sori.studio/deadman-switch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5f9f10f3057c358b8e33c53ffdd43e066ea064d2
deadman-switch/docs/DEPLOY.md
zenn 5f9f10f305 설정 보강 및 메시지 동작 정리 
RESET_TOKEN을 .env에서 읽도록 바꾸고 한국 시간 표시와 시간대별 클릭 메시지 동작을 정리합니다.
2026-06-10 12:42:14 +09:00

7.3 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 폴더

NAS 본체에는 Node.js나 npm이 없어도 됩니다. Docker 이미지 빌드 과정에서 컨테이너 안에서 필요한 패키지를 설치합니다.

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도 함께 확인합니다.

초기화 API 보호 토큰은 Git에 올리지 않는 .env 파일에 넣습니다.

cat > .env <<'EOF'
RESET_TOKEN=여기에-긴-비밀-토큰
EOF

.env 파일이 없으면 Docker Compose 실행 시 RESET_TOKEN 설정 오류가 납니다.

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
  • TZ

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