docs(deploy): add install guide for a domain with HTTPS

- docs/install-guide.md: step-by-step server setup (DNS, Docker, install.sh,
  .env, launch, checks), web and Android client setup, own reverse proxy
  variant, updates, backups and troubleshooting
- deploy/compose.tls.yaml + Caddyfile: optional Caddy with automatic
  Let's Encrypt in front of nginx (enabled via COMPOSE_FILE in .env)
- nginx: honour X-Forwarded-Proto/For from private networks
- .env.example: DOMAIN, ACME_EMAIL, COMPOSE_FILE, bootstrap admin vars
- install.sh: create caddy data dirs; release.yml: ship TLS files as assets
- deployment.md, docs index and README link to the guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

deploy/.env.example

@@ -1,9 +1,17 @@
 # Скопируйте в .env (install.sh делает это сам и генерирует секреты). Описание — docs/deployment.md.
 
 # --- Образы ---
+# Реестр Gitea: <хост>/<владелец>, например gitea.hsrv.site/mrleo1nid
 REGISTRY=git.example.lan/owner
 PIPU_VERSION=0.1.0
 PIPU_DATA=/srv/pipu
+
+# --- Домен и HTTPS (docs/install-guide.md) ---
+# Вариант А: встроенный Caddy с Let's Encrypt — оставьте строку COMPOSE_FILE и заполните DOMAIN, ACME_EMAIL.
+# Вариант Б: свой reverse proxy — закомментируйте COMPOSE_FILE и направьте прокси на HTTP_PORT.
+COMPOSE_FILE=compose.yaml:compose.tls.yaml
+DOMAIN=music.example.com
+ACME_EMAIL=admin@example.com
 HTTP_PORT=80
 
 # --- Секреты (install.sh заполнит случайными значениями) ---
@@ -11,6 +19,10 @@ POSTGRES_PASSWORD=
 MEILI_MASTER_KEY=
 INTERNAL_TOKEN=
 
+# --- Первый администратор (необязательно; иначе пароль генерируется и выводится в лог api один раз) ---
+#BOOTSTRAP_ADMIN_USERNAME=admin
+#BOOTSTRAP_ADMIN_PASSWORD=
+
 # --- api / recommender ---
 # DATABASE_URL собирается в compose.yaml из POSTGRES_PASSWORD
 REDIS_URL=redis://redis:6379/0

deploy/Caddyfile

@@ -0,0 +1,18 @@
+# Caddy: автоматический HTTPS для Pipu Music. Переменные берутся из .env через compose.tls.yaml.
+{
+	email {$ACME_EMAIL}
+}
+
+{$DOMAIN} {
+	encode zstd gzip
+
+	# Загрузки в очередь на добавление идут чанками по 8 МБ (tus)
+	request_body {
+		max_size 16MB
+	}
+
+	reverse_proxy nginx:80 {
+		# не буферизовать стриминг аудио
+		flush_interval -1
+	}
+}

deploy/compose.tls.yaml

@@ -0,0 +1,24 @@
+# HTTPS на своём домене: Caddy получает и продлевает сертификат Let's Encrypt и проксирует на nginx.
+# Подключается через COMPOSE_FILE=compose.yaml:compose.tls.yaml в .env (docs/install-guide.md).
+# Если перед сервером уже стоит свой reverse proxy (Traefik, NPM, nginx) — этот файл не нужен.
+
+services:
+  nginx:
+    # наружу смотрит только Caddy
+    ports: !reset []
+
+  caddy:
+    image: caddy:2.10-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    environment:
+      DOMAIN: ${DOMAIN:?укажите DOMAIN в .env}
+      ACME_EMAIL: ${ACME_EMAIL:?укажите ACME_EMAIL в .env — на него Let's Encrypt пишет о проблемах с сертификатом}
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - ${PIPU_DATA:-/srv/pipu}/caddy/data:/data
+      - ${PIPU_DATA:-/srv/pipu}/caddy/config:/config
+    depends_on: [nginx]

deploy/install.sh

@@ -7,7 +7,7 @@ cd "$(dirname "$0")"
 DATA="${PIPU_DATA:-/srv/pipu}"
 
 echo "→ каталоги в $DATA"
-mkdir -p "$DATA"/{library,library-host,cache/transcode,cache/covers,postgres,meili,redis,models,updates,uploads,backups}
+mkdir -p "$DATA"/{library,library-host,cache/transcode,cache/covers,postgres,meili,redis,models,updates,uploads,backups,caddy/data,caddy/config}
 
 # storage-agent монтирует NFS внутрь $DATA/library; чтобы точки монтирования видели другие контейнеры,
 # каталог должен быть отдельной точкой монтирования с shared propagation.
@@ -44,7 +44,7 @@ if [ ! -f .env ]; then
   cp .env.example .env
   sed -i "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$(secret)|; s|^MEILI_MASTER_KEY=.*|MEILI_MASTER_KEY=$(secret)|; s|^INTERNAL_TOKEN=.*|INTERNAL_TOKEN=$(secret)|; s|^PIPU_DATA=.*|PIPU_DATA=$DATA|" .env
   chmod 600 .env
-  echo "  Проверьте REGISTRY и PIPU_VERSION в .env"
+  echo "  Заполните в .env: REGISTRY, PIPU_VERSION, DOMAIN, ACME_EMAIL"
 fi
 
 echo "Готово. Запуск: ./update.sh \$(grep ^PIPU_VERSION= .env | cut -d= -f2)"

deploy/nginx/default.conf.template

@@ -1,5 +1,11 @@
 # Шаблон обрабатывается envsubst при старте контейнера nginx (переменные: API_UPSTREAM).
-# TLS терминируется здесь или на внешнем прокси — см. docs/deployment.md.
+# HTTPS терминирует внешний прокси: Caddy из compose.tls.yaml или ваш собственный — см. docs/install-guide.md.
+
+# За внешним прокси (Caddy, Traefik, ...) сохраняем исходную схему и IP клиента.
+map $http_x_forwarded_proto $pipu_scheme {
+    default $http_x_forwarded_proto;
+    ''      $scheme;
+}
 
 upstream pipu_api {
     server ${API_UPSTREAM};
@@ -10,6 +16,13 @@ server {
     listen 80;
     server_name _;
 
+    # Доверяем X-Forwarded-For только от частных сетей (docker, LAN), где стоит прокси.
+    set_real_ip_from 10.0.0.0/8;
+    set_real_ip_from 172.16.0.0/12;
+    set_real_ip_from 192.168.0.0/16;
+    real_ip_header X-Forwarded-For;
+    real_ip_recursive on;
+
     root /usr/share/nginx/html;
     client_max_body_size 16m;
 
@@ -23,7 +36,7 @@ server {
         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_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Proto $pipu_scheme;
     }
 
     location = /healthz { proxy_pass http://pipu_api; }