리버스 프록시와 URL base

설정

리버스 프록시 뒤에서 HolyArrs를 https://home.example/holyarrs 같은 주소에 둡니다.

리버스 프록시는 앱들 앞에 서서 각 주소를 알맞은 컨테이너로 보내 주는 웹 서버입니다. URL base(기본 경로)는 HolyArrs가 놓이는 경로입니다.

경로 설정하기

Compose 파일에 경로를 추가하세요.

services:
  holyarrs:
    environment:
      - HOLYARRS_URL_BASE=/holyarrs

컨테이너를 재시작하세요.
프록시 예시에서 프록시 규칙을 골라 추가하세요.
https://home.example/holyarrs/를 여세요. 로그인 페이지가 표시됩니다. Settings > This app(설정 > 이 앱)에 사용 중인 경로가 표시됩니다.

선택 사항

경로를 설정하는 곳

위치	적용 시점
`HOLYARRS_URL_BASE`	시작할 때. 다른 것보다 우선합니다.
`-url-base /holyarrs` 플래그	시작할 때, 변수가 설정되지 않은 경우.
Settings > This app	다음 시작 때, 변수와 플래그가 둘 다 설정되지 않은 경우에만.

프록시 예시

nginx-proxy-manager. 도메인용 프록시 호스트를 만든 다음 custom location을 추가하세요.

Location: /holyarrs
Forward hostname은 holyarrs, 포트는 6262. 끝에 슬래시를 붙이지 마세요. 붙이면 경로가 잘립니다.
그 location의 톱니바퀴 칸에 넣을 내용:

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_buffering off;
proxy_read_timeout 1h;

Traefik. StripPrefix 미들웨어를 추가하지 마세요.

labels:
  - traefik.enable=true
  - traefik.http.routers.holyarrs.rule=Host(`home.example`) && PathPrefix(`/holyarrs`)
  - traefik.http.services.holyarrs.loadbalancer.server.port=6262

Caddy. handle을 쓰세요. handle_path는 경로를 잘라 냅니다.

home.example {
  handle /holyarrs* {
    reverse_proxy holyarrs:6262 {
      flush_interval -1
    }
  }
}

호스트 이름과 프록시 주소

사람들이 호스트 이름으로 HolyArrs에 접속한다면 그 이름을 HOLYARRS_ALLOWED_HOSTS에 추가하세요.
프록시가 X-Forwarded-For를 붙인다면 프록시의 주소를 HOLYARRS_TRUSTED_PROXIES에 추가하세요. 그러지 않으면 로그인할 때 누가 홈 네트워크 안에 있는지 구분하지 못합니다.

문제가 생기면

증상	원인	해결
모든 페이지가 찾을 수 없다고 나옵니다	프록시가 경로를 잘라 냅니다	경로를 자르는 설정이나 끝의 슬래시를 지우세요.
실시간 업데이트가 오지 않습니다	프록시가 응답을 버퍼링합니다	버퍼링을 끄세요(`proxy_buffering off`, `flush_interval -1`).
저장한 경로 때문에 들어갈 수 없습니다	저장한 경로가 잘못되었습니다	`HOLYARRS_URL_BASE=/`로 시작해 저장한 경로를 무시하세요.
로그인할 때 네트워크 밖에 있는 것으로 처리됩니다	프록시가 신뢰 대상이 아닙니다	`X-Real-IP`와 `X-Forwarded-For`를 보내고 `HOLYARRS_TRUSTED_PROXIES`를 설정하세요.

다른 해결 방법은 문제 해결에 있습니다.

전문가용

경로 규칙

쓸 수 있는 문자: 영문자, 숫자, -, _, ., /. ..와 //는 안 됩니다.
holyarrs, /holyarrs, /holyarrs/는 모두 /holyarrs를 뜻합니다.
저장한 경로가 올바르지 않으면 무시됩니다.
모든 것이 경로 아래로 옮겨집니다. 페이지, API, 실시간 업데이트, 로그인, 그리고 HolyArrs가 만드는 링크(초대 링크, 캘린더 피드)까지입니다.
/healthz와 /readyz는 루트에서도 응답하므로 이미지 자체의 상태 점검은 계속 작동합니다.
경로 밖의 다른 주소는 모두 찾을 수 없다고 응답합니다.

프록시가 해야 하는 일

필요한 것	이유
경로를 그대로 넘기기	HolyArrs는 전체 경로로 라우팅합니다.
`Host` 헤더 유지	호스트 확인과 HolyArrs가 만드는 링크에 쓰입니다.
응답 버퍼링 없음	실시간 업데이트는 열려 있는 응답 하나로 계속 흘러옵니다.
긴 읽기 타임아웃(1 h)	실시간 업데이트 스트림이 계속 열려 있습니다.