created by Aha00aAha00a at 2026-08-21
last modified by Aha00aAha00a at 2026-11-18
revision: 24

Dev Deploying

Dev

deploy.sh 는 로컬에서 빌드해 서버에 새 릴리스로 올린다. 서버에 이미 ssh 가 되고 거기서 sudo -n 이 되는 기계에서 돌린다.

AHAWIKI_DEPLOY_HOST=<ssh host>  AHAWIKI_HEALTH_HOST=<a site's domain>  AHAWIKI_PROXY_RELOAD=<command>  bash deploy.sh

어디에 배포하는지는 전부 환경변수에서 온다. 이 저장소는 공개라서 자기 기계 이름을 하나도 적지 않는다.

그것이 경계의 전부이고, 한 문장으로 적을 가치가 있다: 배포가 어떻게 도는지는 이 저장소가 갖고, 그것이 어느 기계에서 일어나는지는 운영을 담는 쪽이 갖는다. 단계·순서·헬스체크·태그 형식·롤백은 전부 여기, 그 모양을 결정하는 코드 옆에 있다. 호스트명·계정·앞단 리버스 프록시는 저쪽에 있고, 이것을 부르는 데는 값들과 한 줄이면 된다:

AHAWIKI_DEPLOY_HOST=… AHAWIKI_HEALTH_HOST=… AHAWIKI_VERIFY_URLS="… …" bash /path/to/AhaWiki/deploy.sh

절차의 사본을 저쪽에도 두면 같은 사실이 두 곳에 있게 되고, 반드시 갈라진다 — 이것이 대체한 사본은 아무도 읽지 않는 디렉터리에 쓸 만큼 낡아 있었다.

AHAWIKI_DEPLOY_HOST

필수 — ssh 호스트 또는 alias

AHAWIKI_HEALTH_HOST

필수 — 위키 중 하나가 답하는 도메인. AHAWIKI_VERIFY_URLS 를 안 주면 https://<이 값>/ 이 확인 대상이 된다. 이름과 달리 5단계의 /hc 폴링은 안 쓴다 — /hc 는 Host 헤더가 필요 없다

AHAWIKI_PROXY_RELOAD

필수 — 서버에서 돌려 앞단 프록시가 «실패한 upstream» 기억을 잊게 하는 명령. 프록시가 무엇인지는 운영 쪽 사실이라 여기 적지 않는다(아래 대기 인스턴스가 먼저 뜨고, 프록시는 잊게 한다)

AHAWIKI_PRIMARY_PORT

10000 — 늘 서비스하는 인스턴스

AHAWIKI_STANDBY_PORT

10001 — 배포 동안만 뜨는 대기 인스턴스

AHAWIKI_CANARY

1 이면 대기 인스턴스를 새 릴리스로 띄우고 멈춘다 — 대조용(아래 대기 인스턴스로 먼저 대조하기)

AHAWIKI_RESTART_ONLY

1 이면 빌드·업로드 없이 current 가 가리키는 릴리스로 인계만 한다 — canary 마무리, 롤백, 설정만 바꾼 재시작

AHAWIKI_REMOTE_ROOT

/opt/ahawiki

AHAWIKI_SERVICE_USER

ahawiki

AHAWIKI_VERIFY_URLS

끝나고 확인할 공개 URL 들, 공백 구분. 5단계에서도 쓴다 — 띄운 인스턴스가 루프백에서 이것들을 전부 그려야 한다

AHAWIKI_KEEP_RELEASES

3

SKIP_TAG

1 이면 배포 태그 생략

1. 무엇을 하는가

릴리스는 releases/ 아래 나란히 놓이고 current 가 그중 하나를 가리키는 심볼릭 링크라서, 배포는 링크를 옮기는 것이고 롤백은 도로 옮긴 뒤 인계만 다시 하는 것이다:

ssh <host> "sudo -n -u ahawiki ln -sfn /opt/ahawiki/releases/<previous> /opt/ahawiki/current"
AHAWIKI_RESTART_ONLY=1 AHAWIKI_DEPLOY_HOST=… AHAWIKI_HEALTH_HOST=… AHAWIKI_PROXY_RELOAD=… bash deploy.sh

손으로 하는 재시작 순서를 여기 따로 적지 않는다. 2026-10-11 까지는 이 자리에 인스턴스마다 재시작하고 기다리는 for 루프가 있었고, 그것은 배포 경로와 따로 낡았다 — 2026-08-16 까지 sleep 20 이라고 적혀 있었다, 배포 경로가 초 세기를 그만둔 지 한참 뒤까지. 롤백은 이미 무언가 잘못됐을 때 도는데, 그때가 손 절차의 낡음을 발견하기에 최악의 순간이다.

cache/ 와 logs/ 는 shared/ 에 살고 각 릴리스에 링크로 들어간다. 어느 릴리스보다도 오래 살기 때문이다.

2. 평소에는 한 대, 배포 때만 두 대

systemd 인스턴스(ahawiki@<port>)는 평소 10000 하나만 리버스 프록시 뒤에서 돈다. 10001 은 대기 인스턴스로, 배포 동안만 뜬다. 프록시는 그것을 backup 으로 둬서, 10000 이 답하지 않는 동안에만 요청을 보낸다. 배포는 이렇다:

  • 10001 을 새 릴리스로 띄워 확인한다. 10000 은 그대로 옛 릴리스로 서비스한다. 여기서 실패하면 current 를 되돌리고 10001 을 내린 뒤 멈춘다 — 독자에게는 아무 일도 없다.
  • 프록시가 실패 기억을 잊게 하고(AHAWIKI_PROXY_RELOAD), 10000 을 재시작한다. 그동안 10001 이 답한다.
  • 10000 이 답하고 그려지면 프록시가 다시 잊게 한 뒤 10001 을 내린다.

왜 한 대인가 — 메모리. 2026-10-11 까지는 둘이 늘 같이 돌며 둘 다 요청을 받았다(2026-09-10 에 [[Uptime]] 을 여덟 번 렌더링하니 JVM 시작 시각 둘이 5:3 으로 번갈아 나왔다). 인스턴스 하나가 상자 메모리의 4분의 1 안팎을 쓴다 — 숫자와 그 분해는 운영 저장소 ahawiki/README.md. 두 대를 둔 이유는 둘이었다: 무중단 배포와, -XX:+ExitOnOutOfMemoryError 로 JVM 이 스스로 죽을 때 다른 대가 받아 주는 것. 앞의 것은 위 순서가 그대로 지킨다. 뒤의 것은 일어난 적이 없었다(2026-10-11 에 셌다): 남은 앱 로그(9-26 부터)에서 JVM 이 시작된 46번이 모두 배포였고 — 10000 의 시작마다 15분 안에 10001 의 시작이 앞섰다 — OutOfMemoryError 는 남은 로그 전체에 0건, old 세대 사용량은 64~138MB 로 -Xmx512m 의 3분의 1 아래였다.

대가. 평소의 한 대가 죽으면 다시 뜰 때까지 프록시가 보낼 곳이 없다. systemd 가 5초 뒤 다시 띄우고 JVM 기동이 약 9초라(2026-10-07 배포의 로그), 그동안 약 15초 502 다. 죽지 않고 멈춘(응답 없는) 경우는 사람이 볼 때까지다 — 두 대일 때도 프록시가 그 대를 시간 초과로 걸러 낼 때까지 절반의 요청이 묶였다.

고르지 않은 것:

  • 두 대를 그대로. 위 대가를 피하는 값으로 상자 메모리의 4분의 1을 늘 쓴다.
  • 두 포트를 번갈아. 배포마다 새 릴리스를 쉬던 쪽에 띄우고 돌던 쪽을 내리면 배포 때 JVM 기동이 한 번 준다. 대신 «지금 어느 쪽이 서비스하는가» 가 배포마다 바뀌어, 운영 명령·표본기·문서가 모두 그것을 따라가야 한다.

되돌리려면 이 변경의 deploy.sh 를 되돌리고(두 대를 차례로 재시작하던 모양), 프록시에서 10001 의 backup 표시를 빼고, 10001 을 다시 enable 해서 띄운다. 인스턴스 사이 장치 — 캐시 무효화의 짧은 만료(Dev Cache «인스턴스가 둘이다»), page.updated 의 Redis 전달(Dev WebSocket) — 는 그대로 두었다. 배포 동안 둘이 함께 뜨고, 되돌릴 때 다시 필요하다.

어느 인스턴스가 답하는지는 지금도 이렇게 본다. /w/ 를 연달아 부르면 봇 차단에 걸리므로 /w/ 밖의 경로로 잰다:

for i in 1 2 3 4 5 6 7 8; do curl -s -X POST -H 'content-type: application/json' -d '{"comment":"[[Uptime]]"}' https://ahawiki.net/api/renderAhaMark/FrontPage; echo; sleep 1; done | sort | uniq -c

AHAWIKI_KEEP_RELEASES 를 넘는 옛 릴리스는 마지막에 지워진다. current 가 가리키는 것은 건너뛴다. 스크립트의 모든 원격 블록은 set -e 로 시작하고, 지우는 블록이 그것이 여전히 그런지 확인해야 하는 이유다. 없으면 releases/ 로의 cd 가 실패해도 아무것도 멈추지 않는다: 루프는 로그인 사용자의 홈 디렉터리를 목록하며 계속 돌고, 거기서는 "이것이 current 인가" 검사에 아무것도 걸리지 않아, 눈에 띄는 가장 오래된 항목들에 sudo rm -rf 를 돌린다. 실패가 아무도 종료코드를 읽지 않는 명령 안에 있어서, 배포는 어느 쪽이든 성공을 보고한다.

3. 대기 인스턴스로 먼저 대조하기

렌더링에 닿는 배포는 대기 인스턴스만 새 릴리스로 띄워 둔다. 그 페이지를 옛 릴리스로 도는 10000 과 대조한 뒤에 인계한다.

AHAWIKI_CANARY=1 AHAWIKI_DEPLOY_HOST=… AHAWIKI_HEALTH_HOST=… AHAWIKI_PROXY_RELOAD=… bash deploy.sh
AHAWIKI_DEPLOY_HOST=… bash scripts/compare-instances.sh 10000 10001
AHAWIKI_RESTART_ONLY=1 AHAWIKI_DEPLOY_HOST=… AHAWIKI_HEALTH_HOST=… AHAWIKI_PROXY_RELOAD=… bash deploy.sh
  • 첫 줄은 평소 배포와 같고, 10001 을 띄워 확인한 데서 멈춘다. current 는 새 릴리스로 옮겨 가지만 10000 은 떠 있던 옛 릴리스에서 계속 돌고 독자는 모두 그쪽으로 간다 — 프록시가 10001 을 backup 으로 두기 때문이다. 2026-10-11 까지는 canary 가 독자의 절반을 받았다. 태그도 이때 붙는다 — 태그는 «서버에 닿아 답했다» 는 뜻이고, 한 대가 답했다.
  • 둘째 줄이 두 대에서 사이트의 모든 페이지를 보기·히스토리로 그려 비교한다. 바뀐 것은 무엇이 바뀌었는지로 묶어 보여 주므로, 모든 페이지에 들어간 템플릿 변경은 한 번만 나온다. 의도한 변경만 나오면 된다. 무엇을 빼고 비교하는지와 결과를 읽는 법은 스크립트 머리말에 있다.

첫 줄이 성공했다는 것은 확인 URL 몇 개가 그려진다는 뜻이지 사이트 전체가 멀쩡하다는 뜻은 아니다. 이 둘째 줄을 건너뛰지 않는다. 2026-10-01 에 첫 줄은 전부 통과했는데 canary 는 모든 페이지에 500 을 답하고 있었다 — 원인은 Dev Resources 의 «운영에서는 jar 안에서 읽는다». 그때 배포가 본 것은 /hc 와 프록시를 거친 확인뿐이었고, 프록시 너머에서는 옛 대가 답했다. 그래서 띄운 대가 확인 URL 을 직접 그리는 확인이 5단계에 들어갔다(아래 그려지는지는 띄운 그 대에서 본다).

  • 괜찮으면 셋째 줄로 인계한다. current 는 이미 새 릴리스이므로 빌드 없이 인계만 한다 — 10001 을 같은 릴리스로 다시 띄우고, 10000 을 재시작하고, 10001 을 내린다. 문제가 있으면 첫 줄이 찍어 준 대로 current 를 되돌리고 10001 을 내린 뒤 태그를 지우고 배포 잠금을 지운다. 10000 은 건드린 적이 없다.

첫 줄부터 셋째 줄까지가 배포 하나다. 그래서 첫 줄은 배포 잠금을 놓지 않고 canary 라고 적어 둔 채 끝나고, 그 잠금을 이어받는 것은 AHAWIKI_RESTART_ONLY 뿐이다(아래 배포는 한 번에 하나).

비교는 서버 안에서 루프백으로 돈다. 인스턴스는 루프백에서만 답하고, 루프백은 화이트리스트라 수백 번 불러도 봇 차단에 걸리지 않는다. 두 대가 같은 릴리스면 비교할 것이 없으므로 스크립트가 거부한다(exit 2) — 어느 릴리스인지는 각 프로세스의 작업 디렉터리로 안다.

2026-09 에는 이 대조를 배포마다 손으로 다시 짰다. 2026-09-26 에는 첫 대조가 231개 중 226개를 «다름» 으로 냈는데, 인접 페이지 그래프가 그릴 때마다 새 UUID 를 쓰기 때문이었다. 그래서 스크립트로 만들었다.

이 대조는 서버가 보내는 HTML 만 본다. 브라우저에서 생기는 일 — 스크립트 예외, 404 를 받는 이미지·요청 — 은 scripts/browser-sweep.mjs 가 본다. 모든 페이지를 헤드리스 Chrome 으로 열어 페이지마다 적는다. 템플릿이나 JS 를 바꾼 배포 뒤에 다 올리고 돌린다. 2026-10-03 에 대조로는 다 «같음» 이던 114개 중 4개에서 이것이 사이트 목록 아이콘의 404 를 찾았다. 쓰는 법과 주의(화이트리스트 주소에서 돌릴 것)는 scripts/README.md.

4. 왜 이런 모양인가

각각이 한 번씩 배포를 부순 값이다.

  • 대기 인스턴스가 먼저 뜨고, 프록시는 잊게 한다. 하나뿐인 인스턴스를 재시작하면 JVM 이 뜨는 동안 받을 곳이 없다. 그래서 대기 인스턴스가 먼저 새 릴리스로 떠서 확인을 통과해야 10000 이 내려간다. 띄울 수 없거나 그려지지 않는 릴리스·설정은 거기서 멈추고, 10000 은 자기가 시작할 때 읽은 것으로 계속 돈다. 설정이 깨져 기동이 실패한 날(2026-08-19, 운영 저장소의 키 교체 기록) 사이트를 지킨 것이 이 «먼저 한 대» 였다.

자기 답만으로는 부족하다. 죽은 upstream 을 떨어뜨리는 프록시는 정해진 간격 동안 그것을 빼놓으므로, 인스턴스가 loopback 에서는 서비스 중인데 프록시는 여전히 아무것도 보내 주지 않을 수 있다 — 그 틈에 다른 대를 내리면 보낼 곳이 남지 않는다. 2026-08-12 배포에서 1초쯤의 502 로 값을 치렀다. 그 뒤로는 «프록시를 거친 요청이 200 이 될 때까지» 기다렸는데, 그 요청은 내리지 않은 다른 대가 답해도 200 이라 실제로는 아무것도 기다리지 않았다. 간격에 맞춘 수를 자면 그 간격이 두 곳에 적힌다. 그래서 프록시를 reload 해 실패 기억을 지운다 — 기다릴 조건을 참으로 만든다. 10000 을 내리기 전에 한 번(대기 인스턴스가 예전 실패로 빠져 있지 않게), 10000 이 돌아온 뒤 대기 인스턴스를 내리기 전에 한 번. 설정 reload 라 진행 중인 요청은 옛 워커에서 끝난다. reload 가 실패하면 떠 있는 것을 다 둔 채 멈춘다.

프록시는 503 도 대기 인스턴스로 넘겨야 한다. 내려가는 Play 는 이미 열려 있던 연결로 들어온 요청에 503 으로 답하는데, 프록시의 기본 재시도는 연결 실패와 시간 초과뿐이다. 2026-10-12 첫 인계에서 10000 이 내려가는 7초에 503 한 건이 샜고, 운영 쪽 프록시 설정에 503 재시도를 더한 뒤의 인계에서는 프록시를 거친 /hc 72건이 모두 200 이었다. 앱은 503 을 스스로 내지 않으므로 이 재시도가 다른 응답을 다시 보내지는 않는다. 남은 틈은 반대쪽 끝이다 — 대기 인스턴스를 내릴 때 그것이 종료 대기(5초)보다 오래 붙잡고 있던 요청은 503 을 받는다. 지금 그런 것은 tarpit 중인 차단 주소의 요청뿐이다(Dev BotDetection). 이 틈은 두기로 했다(2026-10-12). 끊기지 않았어도 그 요청은 어차피 403 을 받았다. 막으려면 deploy.sh 가 대기 인스턴스의 연결이 빠지기를 기다려야 하는데, tarpit 이 최대 55초라 배포마다 그만큼 길어지고, 웹소켓은 스스로 끊기지 않으니 독자가 붙어 있으면 늘 끝까지 기다린다. 다시 볼 때: 정상 요청이 5초 넘게 걸리는 경로가 생기면. 인계 직후 접근 로그에서 «대기 인스턴스를 내린 시각의 503» 을 세면 알 수 있다.

10000 이 새 릴리스에서 실패하면 대기 인스턴스가 대신 받는 채로 두지 않는다. 프록시는 10000 이 무엇이든 답하는 순간 그쪽으로 돌아가므로, 500 을 그리는 10000 이 독자를 받게 된다. 그래서 current 를 이전 릴리스로 되돌려 10000 을 다시 띄우고 대기 인스턴스를 내린다 — 배포 전 그대로다. 그것도 안 되거나 되돌릴 릴리스가 없으면(AHAWIKI_RESTART_ONLY) 10000 을 내리고, 같은 확인을 통과한 대기 인스턴스가 혼자 받게 둔다. 그 상태에서 다시 돌리면 스크립트가 알아보고 대기 인스턴스를 재시작하지 않은 채 10000 부터 띄운다.

  • 배포는 한 번에 하나. 시작하자마자 서버에 /opt/ahawiki/deploy.lock 디렉터리를 만든다. mkdir 는 이미 있으면 실패하므로 그것이 잠금이다. 안의 holder 파일에 상태·배포한 사람@기계·커밋·시각을 적는다. 이미 있으면 그 줄을 보여 주고 빌드 전에 멈춘다(exit 2). 끝나면 성공이든 실패든 지운다.

2026-11-04 에 다른 체크아웃의 배포가 canary 가 대조를 기다리는 동안 인계를 해, canary 의 릴리스를 자기 것으로 바꿔 놓았다. 대조가 엉뚱한 릴리스를 읽고서야 알았다. 잠금이 서버에 있는 것은 그래서다 — 체크아웃·기계가 달라도 같은 것을 본다.

canary 는 잠금을 canary 로 바꿔 둔 채 끝나고, 그것을 이어받는 것은 AHAWIKI_RESTART_ONLY 뿐이다. 이어받을 때 holder 를 옆으로 옮기므로, 둘이 동시에 이어받으려 해도 한쪽만 된다. 실행 중인(deploying) 잠금은 AHAWIKI_RESTART_ONLY 도 넘지 않는다 — 롤백도 진행 중인 배포를 기다린다.

잠금을 쥔 배포가 지우지 못하고 죽으면(ssh 가 끊기는 등) 잠금이 남는다. 멈춤 메시지가 누구의 것인지 보여 주므로, 그 배포가 없다는 것을 확인한 뒤 ssh <host> sudo -n rm -rf /opt/ahawiki/deploy.lock 으로 지운다. 오래된 잠금을 저절로 푸는 시한은 두지 않았다 — 대조는 몇 분이 걸릴지 정해져 있지 않고, 시한이 지나 풀린 canary 잠금은 이번 사고를 그대로 되풀이한다.

  • 헬스체크는 /hc 를 찌른다. 위키 페이지가 아니다. /hc 는 SELECT 1 로 DB 를, 그리고 디스크 여유를 확인하고 OK 를 답한다 — 재시작이 깨뜨릴 수 있는 것들이다. 사이트 매칭을 타지 않으니 Host 헤더도 필요 없다.

그리고 /w/ 밖에 있어야 한다. IpRateLimiter 는 /w/ 아래를 페이지 조회로, 나머지를 사람 신호로 세고, 짧은 창 안에서 페이지만 여러 번 요청한 주소를 차단한다(임계값과 그 이름은 Dev BotDetection). deploy.sh 의 폴링 간격(sleep 3)으로 /w/FrontPage 만 부르는 것이 정확히 그 정의다. 2026-09-04 에 이 루프가 다섯 번째 폴링에서 자기를 차단했다 — 남은 폴링은 403 과 tarpit 을 받았고, 인스턴스가 독자에게 정상 서비스하는 동안 배포는 never became healthy 로 죽었다. 차단은 IpDeny 에 행으로 남고 두 인스턴스가 그 테이블을 공유하므로, 고치지 않았다면 보관 기간 내내 모든 배포가 같은 자리에서 실패했다.

기동이 15초 안에 끝나면 네 번으로 통과한다. 그래서 몇 달간 멀쩡했고, 릴리스가 무거워지자 걸렸다. 폴링 창은 AHAWIKI_HEALTH_TRIES(기본 60 × 3초 = 180초)다. 2026-09-15 에는 두 인스턴스가 같이 뜨며 CPU 를 다투자 차가운 JVM+Play 기동이 첫 대에서 90초(옛 30회 고정)를 넘겨, 멀쩡한 기동을 배포가 실패로 보고하고 한 대를 옛 릴리스에 남긴 채 멈췄다 — 그때는 current 가 이미 새 릴리스를 가리키므로, 남은 한 대를 손으로 재시작해(새 릴리스를 집는다) 마쳤다. 더 느린 장비는 이 값을 올린다. 사이트가 실제로 그려지는지는 /hc 가 통과한 뒤 따로 본다(바로 아래) — /hc 폴링이 넓게 볼 이유가 없다. 7단계는 태그일 뿐 아무것도 확인하지 않는다.

  • 그려지는지는 띄운 그 대에서 본다. /hc 가 통과하면 그 포트에 루프백으로 AHAWIKI_VERIFY_URLS 를 하나씩 그려 본다(Host 헤더는 URL 의 호스트). 프록시를 거치면 다른 대가 대신 답할 수 있다 — 2026-10-01 에 모든 페이지가 500 인 canary 를 배포가 성공으로 보고한 이유다. 대기 인스턴스가 하나라도 200 이 아니면 current 를 이전 릴리스로 되돌리고 그것을 내린 뒤 멈춘다. 10000 이 그러면 위 대기 인스턴스가 먼저 뜨고, 프록시는 잊게 한다 의 마지막 문단대로다. 루프백은 화이트리스트라 이 요청들은 봇 차단에 세지 않는다. 확인 URL 몇 개만 보므로 렌더링에 닿는 배포의 대조(위 대기 인스턴스로 먼저 대조하기)를 대신하지는 않는다. 되돌리는 길은 운영 인스턴스에 그 함수만 돌려 본 것(정상 URL 은 통과, 403·404 는 잡힌다)이고, 실제 배포에서 돈 적은 아직 없다.
  • 외부 확인은 리다이렉트를 따라간다. 303 을 답하는 첫 페이지는 그것이 어디로 가는지에 대해 아무 말도 하지 않는다. 뒤의 모든 페이지가 500 인 동안 303 으로 통과한 배포가 있었다.
  • 외부 확인은 재시도한다. 처음에는 프록시의 «빼놓는 간격» 을 기다리려는 것이었다 — 마지막 재시작이 헬스체크를 통과한 순간에 확인하면 멀쩡한 배포에서 502 를 읽었고, 좋은 릴리스의 태그 하나를 값으로 치렀다. 이제 5단계가 프록시를 reload 하므로 그 이유는 사라졌고, 첫 시도가 통과하면 비용이 없어 그대로 둔다. canary 에서는 외부 확인을 하지 않는다 — 프록시가 독자를 옛 릴리스로 보내고 있으니 새 릴리스에 대해 말해 주는 것이 없다.
  • 업로드는 rsync 가 아니라 tar over ssh 다. Git Bash 에서 MSYS2 rsync 를 부르면 두 MSYS 런타임을 건너느라 인자가 뭉개져 도착하고, 아무것도 복사하기 전에 죽는다.
  • 태그는 맨 마지막에 쓴다. 검증 뒤에 써서, "이것이 빌드됐다" 가 아니라 "이것이 서버에 닿아 답했다" 를 뜻하게 한다.
  • conf/evolutions 가 바뀐 배포는 백업을 먼저 본다. 스크립트는 이것을 하지 않는다 — 어느 데이터베이스인지가 운영 쪽 사실이라서다. 확인 명령과 멈춰야 할 값은 운영 저장소 ahawiki/README.md 에 있고, 읽기 전용 한 줄이다. 2026-09-02 에 evolution 둘이 이것 없이 나갔다. 안전망은 있었지만 그것을 안 것은 배포 뒤였고, 그날 두 번째 배포는 실제로 실패해 되돌려야 했다(Dev Database).

5. CSS·JS 주소에는 내용 해시가 붙는다

/public/ 아래 파일은 Play 기본값 그대로 Cache-Control: public, max-age=3600 으로 나간다. 2026-09-27 까지는 템플릿이 그 파일들을 고정 주소(/public/wiki.css)로 불러서, 배포 전 한 시간 안에 사이트를 연 브라우저는 새 HTML 을 옛 CSS·JS 로 그렸다. 2026-09-26 배포 직후 옛 리비전 안내 상자(Dev Page)가 이렇게 색 없이 보였다 — 서버는 이미 새 CSS 를 주고 있었다. HTML 과 JS 를 같이 바꾼 배포라면 그 한 시간 동안 새 HTML 이 옛 JS 를 불렀다.

이제 템플릿은 위키 자신의 CSS·JS 를 PublicAsset.url 로 부르고, 그것이 주소 뒤에 파일 내용의 해시를 붙인다(/public/wiki.css?v=…). 내용이 바뀐 파일은 어느 브라우저도 캐시한 적 없는 새 주소가 되고, 안 바뀐 파일은 주소도 캐시도 그대로다. 파일은 여전히 Play 의 Assets 가 보낸다 — 캐시 헤더만 PublicAssets 가 바꾼다. v 가 맞지 않으면 no-cache(아래 남은 틈), 맞으면 1년 immutable 이다(2026-11-02 부터). 그 주소는 그 내용만 뜻하므로 다시 물을 이유가 없다.

  • 해시는 인스턴스마다 파일당 한 번, 실제로 서비스되는 파일(classpath 의 public/…)에서 계산한다. 릴리스는 새 디렉터리와 재시작이라 도는 중에는 파일이 바뀌지 않는다. 배포가 admin.js 를 다시 빌드해도 해시는 실제로 나가는 쪽을 따른다. dev 모드(sbt run)에서는 파일을 고쳐도 해시가 다음 reload 까지 그대로인데, dev 모드는 자산을 no-cache 로 내보내므로 브라우저가 매번 다시 묻는다.
  • 템플릿에 CSS·JS 를 새로 넣을 때도 PublicAsset.url 로 부른다. 맨 주소로 쓰면 그 파일은 예전처럼 배포 뒤 최대 한 시간 늦게 닿는다. test/templates.public-assets.test.mjs 가 맨 주소와 없는 파일 이름을 잡고, PublicAssetVersionSpec 은 렌더된 페이지의 해시가 그 주소에서 실제로 받는 내용의 해시인지 본다.
  • 관리 화면의 import map 값도 같다(2026-10-31 부터). _baseAdmin.scala.html 이 React·Mantine 등을 public/js/babel/vendor/ 의 파일로 가리키는데, 그 값은 속성이 아니라 JSON 문자열이라 PublicAssetVersionSpec 의 정규식이 그 모양도 읽는다. vendor 파일끼리 서로 부르는 청크(chunk-<hash>.js)에는 ?v= 가 없다 — 이름에 내용 해시가 있어 다시 빌드되면 다른 주소가 되므로 같은 효과다. 왜 esm.sh 에서 여기로 왔는지는 scripts/README.md.
  • 서드파티 CSS·JS 도 같다(2026-10-31 부터). jQuery·MathJax·mermaid 같은 것을 페이지가 CDN 대신 public/vendor/ 에서 받는데(scripts/vendor.mjs 가 node_modules 에서 복사, 왜는 scripts/README.md «Vendored page assets»), 템플릿이 그 파일을 부르는 자리도 PublicAsset.url 이다. MathJax 가 자기 밑에서 더 불러오는 글꼴·jax 와 Font Awesome·Pretendard 의 웹폰트에는 ?v= 가 없고 한 시간 캐시를 그대로 받는다 — 버전을 올리면 MathJax 는 제 ?V=버전 을 붙이고 글꼴은 이름이 같아도 내용이 거의 안 바뀐다.
  • 이미지·파비콘과 CSS 안의 url(…) 에는 붙이지 않았다. 배포에서 HTML 과 맞물려 바뀌는 일이 없어서, 한 시간 늦어도 깨지는 것이 없다.
  • 앞단 리버스 프록시가 query string 을 그대로 넘기고 캐시하지 않아야 이것이 듣는다. 2026-09-27 운영에서 /public/wiki.css 와 ?v= 를 붙인 주소가 같은 파일을 같은 Cache-Control 로 돌려줬고, 캐시 헤더(Age 같은)는 없었다. 앞단에 query 를 캐시 키에서 빼는 캐시를 두면 이 방식은 소리 없이 무력해진다.

고르지 않은 것:

  • sbt-digest 와 routes.Assets.versioned — 파일 이름에 해시를 넣고 1년 캐시한다. 플러그인과 파이프라인 단계가 늘고, 해시는 sbt stage 에서만 생겨 sbt run·sbt test 에서는 볼 수 없다. 배포 중 두 인스턴스가 섞인 동안 한쪽에 없는 이름을 받으면 404 라 그 화면은 스타일 없이 그려진다.
  • 릴리스나 커밋을 query 에 — 빌드나 배포가 그 값을 앱에 따로 넣어 줘야 하고, 배포마다 안 바뀐 파일까지 전부 다시 받게 한다.
  • /public/ 전체의 max-age 늘리기 — 맨 주소는 3600 그대로다. 전체에 걸리는 값이라 해시가 없는 이미지까지 길어진다. 해시가 맞는 주소만 늘린 것은 이 문제가 없고, 아래 남은 틈도 넓히지 않는다 — 어긋난 응답은 no-cache 라 1년이 붙지 않는다.

남은 틈 — 릴리스가 바뀌는 순간. 새 HTML 이 부른 ?v=<새 해시> 가 옛 릴리스로 도는 인스턴스로 가면, 옛 인스턴스는 옛 파일을 준다. 그대로 두면 그 브라우저는 옛 파일을 새 주소로 최대 한 시간 캐시한다 — 배포가 끝난 뒤에도. 2026-10-11 까지는 새 인스턴스와 옛 인스턴스가 같이 요청을 받는 동안이 배포마다 있었다 — 보통 배포는 몇 초, canary 는 대조를 마칠 때까지. 이제 독자를 받는 쪽은 한 번에 하나라(위 평소에는 한 대, 배포 때만 두 대) 그 동안은 10000 이 내려가는 순간 진행 중이던 요청 정도로 줄었다. 옛 HTML 을 들고 있는 브라우저가 새 인스턴스에 옛 v 를 묻는 반대 경우는 배포마다 그대로 생긴다.

그래서 /public/ 은 PublicAssets 컨트롤러가 받는다. 파일은 Assets 가 그대로 보내고, v 가 그 인스턴스가 가진 파일의 해시와 다르면 max-age 대신 no-cache 를 붙인다. 섞인 동안 받은 파일은 다음 페이지에서 다시 물어 바로잡힌다. 옛 HTML 의 v 를 새 인스턴스가 받는 반대 경우도 같다. PublicAssetCacheSpec 이 확인하는데, Prod 모드로 띄운다 — Assets 는 Prod 에서만 max-age 를 붙이고 Dev·Test 에서는 아무것도 안 붙여, 다른 모드에서는 이 검사가 컨트롤러가 없어도 통과한다.

이것은 옛 인스턴스 쪽에 있어야 듣는다. 그래서 이 코드가 들어간 배포(2026-10-02) 자체는 아직 막지 못하고, 그다음 배포부터 막는다.

그러니 배포 직후 눈으로 본 화면이 이상하면 여전히 강력 새로고침부터 해 본다. HTML 과 맞물려야 하는 JS 변경도 그동안은 어긋날 수 있다. CSS·JS 를 바꾼 배포는 대조에서 모든 페이지의 그 ?v= 가 바뀐 것으로 나온다 — 의도한 변경이다.

6. JDK 를 갈면 재시작 전까지 프로세스 실행이 막힌다

돌고 있는 JVM 아래에서 JDK 패키지가 갈리면, 그 프로세스는 자식 프로세스를 하나도 띄우지 못한다. 예외는 IOException: Cannot run program "sh": error=0, Failed to exec spawn helper 이고, 까닭은 JVM 이 fork 할 때 쓰는 jspawnhelper 가 제가 떠 있는 JDK 의 것이라야 하는데 그 파일이 이미 다른 것으로 갈려 있기 때문이다. 돌고 있는 프로세스의 /proc/<pid>/exe 가 (deleted) 로 보이는 것이 신호다.

ssh <host> "sudo -n readlink -f /proc/\$(systemctl show ahawiki@10000 -p MainPID --value)/exe"

2026-09-25 에 실제로 그 상태였다. 인스턴스는 9-20 19:06 부터 돌고 있었고, JDK 는 9-23 06:29 에 unattended-upgrade 가 갈았다(/var/log/apt/history.log: openjdk-17 17.0.20+8 → 17.0.20.1+1). 즉 사람이 한 일이 아니고, 다음 JDK 보안 업데이트에도 같은 일이 난다. AhaWiki 에서 자식 프로세스를 띄우는 곳은 InterpreterVim 의 vi 하나뿐이라, 증상은 캐시에 없는 Vim 블록을 그리는 문서가 전부 500 이었다 — 이미 캐시에 있는 블록은 멀쩡해서 사이트는 정상으로 보였다. 3일간 아무도 몰랐다.

고치는 방법은 재시작뿐이다. 배포는 어차피 재시작하므로 배포 한 번이 곧 치료다. 다시 나지 않게 하려면 둘 중 하나인데 아직 어느 쪽도 하지 않았다.

  • 서버 쪽: apt 가 openjdk 를 올리면 ahawiki@* 를 재시작하는 hook(DPkg::Post-Invoke). 운영 저장소의 일이다.
  • 앱 쪽: JVM 을 -Djdk.lang.Process.launchMechanism=VFORK 로 띄운다. jspawnhelper 를 안 쓰므로 JDK 가 갈려도 프로세스를 띄울 수 있다. 이 앱이 띄우는 프로세스는 vi 하나뿐이라 부담이 없다. systemd unit 의 한 줄이라 이것도 운영 쪽이다.

그 사이에는 InterpreterVim 이 강조 없이 본문을 보여 주는 것으로 버틴다(InterpreterVim).

7. 비밀이 든 설정을 conf/ 밖에

sbt stage 는 conf/ 아래 모든 파일을 릴리스에 복사한다. gitignore 는 거기 관여하지 못한다 — git 이 무엇을 추적하는지를 다스릴 뿐, 빌드가 무엇을 패키징하는지는 아니다 — 그래서 거기 둔 로컬 설정은 배포마다 서버로 따라간다.

가정이 아니다. 개발 DB 비밀번호와 play.http.secret.key 가 릴리스 세 개에, world readable 로, 앱이 열지도 않는 파일에 앉아 있었다: 앱은 릴리스 밖을 가리키는 절대 경로 -Dconfig.file 로 시작된다. 지금 구조가 시작된 뒤로 배포마다 나가고 있었다.

build.sbt 는 이제 git 에게 conf/ 아래 무엇을 추적하는지 물어 그것만 패키징한다. ignore 된 파일은 실리지 않는다 — 모두가 이미 그런 줄 알았던 바로 그것이다. 무엇을 뺐는지도 말한다:

[info] conf/: not packaged (untracked): conf/something.local.conf

파일명 패턴을 먼저 시도했고, git 이 없는 빌드의 폴백으로만 남겼다. 패턴은 누군가 떠올린 모양들을 잡는데, 이 일의 발단이 된 파일은 그중 어느 모양도 아니었다: 호스트명을 따서 지은 이름이었다.

그 폴백은 2026-08-15 에 처음 실제로 돌려 봤다 — git 을 PATH 에서 빼고, 미끼 파일 둘을 심어서: 하나는 *.local.*, 하나는 호스트명을 딴 이름. 설계대로 동작했고 한계도 위에 적은 그대로다: 첫째는 빠졌고 둘째는 실렸다. 그래서 폴백은 경고하고, 이제 패키징하려는 conf/ 최상위 목록도 찍는다. "릴리스를 확인하라" 는 뺀 것의 목록으로는 답할 수 없기 때문이다 — 걱정할 파일은 정의상 패턴이 알아보지 못한 그 파일이다.

[warn] conf/: git unavailable, falling back to name patterns. Check the release for local configs.
[warn] conf/: packaged on the name rule alone: conf/application.conf
[warn] conf/: packaged on the name rule alone: conf/base.conf
...

여섯 줄쯤이고, 낯선 설정 하나는 거기 끼면 눈에 띈다. 하위 디렉터리는 그 목록에서 뺐다 — 기본 페이지와 evolution 전부는 하나를 숨기기에 충분히 길다. git 이 있으면 이것들은 하나도 나타나지 않는다. 보통의 빌드가 전부 그쪽이다.

배포 설정이 conf/ 에 살아야 할 이유는 아무것도 없다 — 서버는 절대 경로로 설정 위치를 받는다 — 그러니 가장 안전한 자리는 여전히 아예 다른 곳이다.

8. 앞단 nginx 는 경로를 풀지 않는다

위키로 가는 proxy_pass 끝에는 / 를 붙이지 않는다(2026-10-04 소유자 결정). 붙이면 nginx 가 경로의 %22·%5B·%3C 를 "·[·< 로 풀어서 넘기고, Play 는 그런 경로를 읽지 못해 400 을 낸다("Cannot parse path from URI") — Tip "T.I." Harris 같은 이름의 링크가 그랬다. 바꾼 곳과 되돌릴 백업은 운영 저장소 ahawiki/README.md «앞단 nginx».

대가가 둘 있다.

  • nginx 가 더는 // 를 하나로 합쳐 주지 않는다 — //public/less.css 는 404 다. 위키가 만드는 주소에 // 가 생기면 안 된다. 페이지 대표 이미지의 주소는 Api.pageImageUrl 한 곳에서 만든다(전에는 그래프용 사본이 / 로 시작하는 이미지를 https://<host>//… 로 만들었다). 검사는 PageImageUrlSpec.
  • 퍼센트 인코딩 없이 UTF-8 바이트 그대로 온 경로는 Pekko 가 400 으로 거절한다. 받아 주려면 nginx 가 다시 인코딩하게 해야 하는데 이 결정과 부딪힌다. 브라우저는 늘 인코딩해 보내므로 봇만 걸린다(Dev Logs «2026-10-31 에 나온 것»).

9. 전에 여기 있던 것

2026-08-12 까지 이 저장소에는 다른 배포 장치 둘이 실려 있었고 둘 다 더는 서버와 맞지 않았다: 옛 경로에 빌드를 덮어 복사하는 스크립트 하나, 서버에서 빌드해 pm2 로 띄우는 GitHub Actions 워크플로 하나. 운영은 current 에서 도는 systemd 서비스로 옮겨 간 뒤라, 스크립트는 아무도 읽지 않는 디렉터리에 썼고 워크플로는 돌고 있는 서비스와 포트를 두고 경합했을 것이다. 둘 다, 의존하던 pm2 launch 스크립트·process 파일과 함께 제거했다.

10. See Also

10.2. Similar Pages

Similar pages by cosine similarity. Words after page name are term frequency.

  • 36.37% Dev RunningLocally ahawiki(53:4), conf(17:16), 않는다(25:6), host(21:7), 배포(25:1), dev(13:9), 다시(20:1), 없다(15:5), 같은(13:6), 있는(9:9)
  • 33.63% Dev Database ahawiki(53:1), 않는다(25:11), 다시(20:12), 같은(13:19), 다른(11:20), 배포(25:2), 대기(23:1), conf(17:7), db(2:19), dev(13:7)
  • 33.46% Setup ahawiki(53:21), 않는다(25:8), site(1:29), 다시(20:6), 대기(23:1), 없다(15:7), conf(17:4), 같은(13:7), net(1:19), 인스턴스가(18:1)
  • 31.23% Dev Logs ahawiki(53:1), dev(13:23), 같은(13:20), 10000(26:3), 배포(25:4), 다시(20:5), host(21:1), 없다(15:7), 있다(9:13), 인스턴스가(18:3)
  • 31.14% Dev Page page(7:89), ahawiki(53:3), wiki(5:43), 페이지(3:40), 않는다(25:15), 다시(20:20), 같은(13:27), 그대로(13:17), 배포(25:4), url(12:17)

10.3. Adjacent Pages

≤ 32
all
1.0x
1.0x
80
-120
ON
0/0
0/0
0.00
0
0 / 0
1.00x