Как перевести Runtipi на внешний PostgreSQL

Для перевода Runtipi на внешний PostgreSQL используйте официальный метод через файл .env.local и запуск runtipi-cli с флагом --env-file. Это позволяет переопределить docker compose переменные окружения, такие как POSTGRES_HOST, без модификации генерируемого .env. Runtipi внешний PostgreSQL подключается после полной остановки стека, дампа данных и запуска CLI с кастомным окружением — так CLI не перезапишет настройки.

Содержание

• Архитектура Runtipi и роль PostgreSQL
• Подготовка внешнего сервера PostgreSQL
• Создание и настройка .env.local
• Миграция данных из встроенного контейнера
• Запуск Runtipi с внешним PostgreSQL
• Почему переменные окружения не применяются и как исправить
• Проверки и мониторинг после миграции

Архитектура Runtipi и роль PostgreSQL

Runtipi — это платформа для управления контейнерами, где основной стек включает сервисы runtipi, runtipi-reverse-proxy, runtipi-queue и runtipi-db на базе образа postgres:14. Документация по структуре папок подчеркивает, что файл .env генерируется автоматически CLI при каждом запуске и содержит все ключевые параметры, включая пароли БД, версии и пути. Ручное редактирование .env бесполезно — он перезаписывается.

Встроенный runtipi-db жестко прописан в docker-compose.yml как сервис с именем runtipi-db, поэтому POSTGRES_HOST по умолчанию равен этому имени. Обзор CLI описывает, как CLI управляет lifecycle контейнеров: он парсит .env (или .env.local), генерирует compose-файл и запускает стек. Для внешнего PostgreSQL нужен override через .env.local, чтобы docker переменные окружения контейнера подменили дефолтные значения вроде POSTGRES_HOST=runtipi-db.

Если вы установили Runtipi v4.6.5 в LXC на Proxmox по скрипту bash -c "$(wget -qLO - install.samohosting.ru)", рабочий каталог /opt/runtipi содержит все файлы. Остановка runtipi-db обязательна, иначе стек не запустится из-за зависимостей.

Подготовка внешнего сервера PostgreSQL

Ваш внешний PostgreSQL уже доступен в сети и проверен через psql — отлично, это минимизирует сетевые проблемы. Убедитесь в совместимости версий: проблема в репозитории appstore показывает, что Runtipi ожидает PostgreSQL 13+, ваш postgres:14 подходит.

На внешнем сервере:

1. Создайте БД и пользователя:

   sudo -u postgres psql
   CREATE DATABASE runtipi_db;
   CREATE USER runtipi_user WITH PASSWORD 'your_strong_password';
   GRANT ALL PRIVILEGES ON DATABASE runtipi_db TO runtipi_user;
   \q
   

2. Настройте postgresql.conf и pg_hba.conf для доступа из LXC (IP вашего хоста или подсети Proxmox):

   host    runtipi_db    runtipi_user    192.168.x.x/24    md5
   

   Перезапустите PostgreSQL: sudo systemctl restart postgresql.

3. Проверьте подключение из LXC:

   psql -h <external_ip> -U runtipi_user -d runtipi_db
   

Дополнительно изучите переменные окружения PostgreSQL, чтобы PGHOST, PGPORT=5432, PGDATABASE и т.д. были готовы для docker compose переменные окружения.

Создание и настройка .env.local

Канонический способ — .env.local для override. CLI его уважает при --env-file. В /opt/runtipi создайте .env.local:

POSTGRES_HOST=<external_ip_или_hostname>
POSTGRES_PORT=5432
POSTGRES_DBNAME=runtipi_db
POSTGRES_USERNAME=runtipi_user
POSTGRES_PASSWORD=your_strong_password
POSTGRES_SSL=false  # если без SSL, иначе true и настройте сертификаты

Не трогайте другие переменные — CLI подхватит остальное из дефолта. Защитите файл: chmod 600 .env.local.

Почему ваши попытки провалились? docker compose config без --env-file читает базовый .env, где POSTGRES_HOST=runtipi-db. CLI генерирует compose на лету, игнорируя прямые правки docker-compose.yml.

Миграция данных из встроенного контейнера

Перед миграцией остановите стек:

cd /opt/runtipi
sudo ./runtipi-cli down

Дамп из runtipi-db (если контейнер еще жив):

docker compose exec -T runtipi-db pg_dumpall -U postgres > runtipi_backup.sql
# Или только runtipi_db: pg_dump -U postgres -d runtipi_db > runtipi_db.sql

Восстановите на внешнем:

psql -h <external_ip> -U runtipi_user -d runtipi_db -f runtipi_backup.sql

Учтите схемы вроде drizzle — ошибки CREATE SCHEMA возникают, если дамп неполный или права недостаточны. После дампа удалите volumes runtipi-db: docker volume rm $(docker volume ls -q | grep runtipi-db).

Запуск Runtipi с внешним PostgreSQL

Полная последовательность Runtipi внешний PostgreSQL:

1. Остановите все: sudo ./runtipi-cli down.

2. Удалите/переименуйте .env временно: mv .env .env.backup (CLI сгенерирует новый на основе .env.local).

3. Запустите с override:

   sudo ./runtipi-cli start --env-file ./.env.local
   

4. В docker-compose.yml (после генерации) увидите environment: с вашими POSTGRES_*. Не останавливайте runtipi-db вручную — CLI пропустит его, если POSTGRES_HOST внешний.

Теперь каждый запуск/рестарт: всегда с --env-file, иначе реверт к дефолту. Автоматизируйте в cron или скрипте:

#!/bin/bash
cd /opt/runtipi
sudo ./runtipi-cli restart --env-file ./.env.local

Почему переменные окружения не применяются и как исправить

Вопрос 1: Правильный способ — runtipi-cli с --env-file ./.env.local. Прямые правки docker-compose.yml или .env не поддерживаются, так как CLI регенерирует их. Нет другого официального метода.

Вопрос 2: docker inspect показывает env на старте контейнера из compose, но внутри может отличаться из-за:

• Docker Compose multi-env: базовый .env + --env-file сливаются, но приоритет у первого.
• Runtipi CLI пост-обработка: генерирует compose с хардкодом runtipi-db, если не видит override.
• Проверка внутри: docker exec -it runtipi env | grep POSTGRES_ после полного старта.

Решение: docker compose --env-file ./.env.local down && docker compose --env-file ./.env.local up -d.

Вопрос 3: Да, CLI имеет слой генерации: парсит .env → шаблонит compose → POSTGRES_HOST fallback на runtipi-db. .env.local с --env-file обходит это. Если chmod 444 .env — CLI может сломаться.

Другие ошибки:

• Сеть LXC-Proxmox: добавьте network_mode: host или bridge.
• Логи: docker logs runtipi покажут миграции Drizzle.
• Версия: v4.6.5 совместима, но обновите CLI если нужно.

Проверки и мониторинг после миграции

После запуска:

docker compose --env-file ./.env.local ps  # все up кроме runtipi-db
docker exec -it runtipi env | grep POSTGRES_  # ваши значения
curl http://localhost:3000  # веб-интерфейс

Мониторьте: docker stats, логи PostgreSQL. Если сбои — дамп/восстановление заново. В проде используйте внешний мониторинг (Prometheus в Runtipi-apps).

Для LXC специфика: убедитесь, что Proxmox сеть пропускает 5432 порт.

Источники

• https://runtipi.io/docs/reference/folder-structure
• https://deepwiki.com/runtipi/cli/1-overview
• https://github.com/runtipi/runtipi-appstore/issues/8030
• https://learnomate.org/essential-postgresql-environment-variable/
• https://deepwiki.com/runtipi/cli/1.1-getting-started

Заключение

Переход Runtipi на внешний PostgreSQL через .env.local и runtipi-cli --env-file — единственный канонический путь, обходящий регенерацию файлов. После дампа данных и проверок стек заработает стабильно, с docker compose переменные окружения на месте. Если логи покажут проблемы — поделитесь docker-compose.yml и .env.local для точной диагностики. Это усилит производительность и масштабируемость вашей установки в Proxmox.