Обратный прокси и URL base

Разместите HolyArrs по адресу вроде https://home.example/holyarrs за вашим обратным прокси.

Обратный прокси — это веб-сервер перед вашими приложениями, который направляет каждый адрес в нужный контейнер. URL base — это путь, по которому живёт HolyArrs.

Задать путь

1. Добавьте путь в Compose-файл:

   services:
     holyarrs:
       environment:
         - HOLYARRS_URL_BASE=/holyarrs

2. Перезапустите контейнер.

3. Добавьте правило прокси из раздела Примеры для прокси.

4. Откройте https://home.example/holyarrs/. Вы увидите страницу входа. В Settings > This app (Настройки > Это приложение) показан путь, который сейчас используется.

Осторожно

Прокси должен передавать путь без изменений. Если он отрезает /holyarrs, каждая страница отвечает «not found».

Варианты выбора

Где задать путь

Где	Когда начинает действовать
HOLYARRS_URL_BASE	При запуске. Важнее остальных.
Флаг -url-base /holyarrs	При запуске, если переменная не задана.
Settings > This app	При следующем запуске, только если не заданы ни переменная, ни флаг.

Примеры для прокси

nginx-proxy-manager. Создайте proxy host для своего домена и добавьте 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. Не добавляйте middleware 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. Без этого вход не может определить, кто находится в вашей домашней сети.

Если не работает

Признак проблемы	Причина	Решение
Каждая страница отвечает «not found»	Прокси отрезает путь	Уберите настройку, которая отрезает путь, или косую черту в конце.
Живые обновления не приходят	Прокси буферизует ответы	Выключите буферизацию (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 отвечают ещё и в корне, поэтому собственная проверка исправности образа продолжает работать.
• Любой другой адрес вне пути отвечает «not found».

Что должен делать прокси

Что нужно	Зачем
Передавать путь без изменений	HolyArrs выбирает маршрут по полному пути.
Сохранять заголовок Host	Он нужен для проверки хоста и для ссылок, которые строит HolyArrs.
Не буферизовать ответы	Живые обновления идут потоком через один открытый ответ.
Долгий тайм-аут чтения (1 ч)	Поток живых обновлений остаётся открытым.

См. также

• Установка
• Вход
• Переменные окружения