Установка pgAdmin 4 через Python venv с Nginx (без Apache)

Методичка по развёртыванию pgAdmin 4 в изолированном Python-окружении с запуском через Gunicorn и проксированием через Nginx. Apache не используется.

---

Содержание

1. Требования
2. Шаг 1. Подготовка зависимостей и создание venv
3. Шаг 2. Установка pgAdmin и Gunicorn
4. Шаг 3. Настройка config_local.py
5. Шаг 4. Инициализация pgAdmin
6. Шаг 5. Создание Systemd-сервиса
7. Шаг 6. Настройка Nginx
8. Проверка
9. Обновление pgAdmin
10. Диагностика

---

Требования

• Debian 13 (Trixie) или совместимый дистрибутив
• Python 3.13
• root-доступ или sudo
• Уже работающий сайт на Nginx (если нужен доступ по подпути)

---

Шаг 1. Подготовка зависимостей и создание venv

Устанавливаем системные библиотеки и создаём изолированное окружение.

sudo apt update
sudo apt install -y python3-venv python3-pip libpq-dev libgmp3-dev build-essential

# Создаём директорию для pgAdmin
sudo mkdir -p /opt/pgadmin4
sudo chown $USER:$USER /opt/pgadmin4
cd /opt/pgadmin4

# Создаём и активируем виртуальное окружение
python3 -m venv venv
source venv/bin/activate

Важно: Команда python3 -m venv venv создаст папку venv внутри /opt/pgadmin4. Все дальнейшие команды pip должны выполняться внутри этого окружения.

---

Шаг 2. Установка pgAdmin и Gunicorn

pip install --upgrade pip wheel
pip install pgadmin4 gunicorn

Убедитесь, что путь к site-packages соответствует вашей версии Python:

find /opt/pgadmin4/venv -name "pgadmin4" -type d

Пример результата: /opt/pgadmin4/venv/lib/python3.13/site-packages/pgadmin4

---

Шаг 3. Настройка config_local.py

Создайте файл конфигурации:

nano /opt/pgadmin4/venv/lib/python3.13/site-packages/pgadmin4/config_local.py

Содержимое:

import os

# Директория для данных pgAdmin
DATA_DIR = '/opt/pgadmin4/data'

# Пути к файлам
LOG_FILE = os.path.join(DATA_DIR, 'pgadmin4.log')
SQLITE_PATH = os.path.join(DATA_DIR, 'pgadmin4.db')
SESSION_DB_PATH = os.path.join(DATA_DIR, 'sessions')
STORAGE_DIR = os.path.join(DATA_DIR, 'storage')

# Режим сервера (обязательно для веб-доступа)
SERVER_MODE = True

Создайте директорию для данных:

mkdir -p /opt/pgadmin4/data

---

Шаг 4. Инициализация pgAdmin

Запустите скрипт настройки, который создаст базу данных и запросит email и пароль для входа.

cd /opt/pgadmin4/venv/lib/python3.13/site-packages/pgadmin4
python setup.py setup-db

Введите Email и Password. Эти данные будут использоваться для входа в веб-интерфейс.

Примечание: Предупреждение UserWarning: Unnamed CHECK constraint... в выводе — это известное безобидное предупреждение Alembic, его можно игнорировать.

---

Шаг 5. Создание Systemd-сервиса

Чтобы pgAdmin работал как служба и запускался автоматически, создаём unit-файл.

5.1. Создание отдельного пользователя

sudo useradd -r -s /bin/false pgadmin
sudo chown -R pgadmin:pgadmin /opt/pgadmin4

5.2. Создание unit-файла

sudo nano /etc/systemd/system/pgadmin4.service

Содержимое:

[Unit]
Description=pgAdmin4 Service
After=network.target

[Service]
Type=simple
User=pgadmin
Group=pgadmin
WorkingDirectory=/opt/pgadmin4/venv/lib/python3.13/site-packages/pgadmin4
Environment="PATH=/opt/pgadmin4/venv/bin"
ExecStart=/opt/pgadmin4/venv/bin/gunicorn \
    --bind unix:/run/pgadmin4/pgadmin4.sock \
    --workers=1 \
    --threads=25 \
    --chdir /opt/pgadmin4/venv/lib/python3.13/site-packages/pgadmin4 \
    pgAdmin4:app
Restart=always

# Автоматически создаёт /run/pgadmin4 при старте и удаляет при остановке
RuntimeDirectory=pgadmin4
RuntimeDirectoryMode=0750
RuntimeDirectoryPreserve=restart

[Install]
WantedBy=multi-user.target

Почему /run/pgadmin4, а не /tmp:

• Каталог /tmp периодически очищается системой (systemd-tmpfiles), что может привести к удалению сокета работающего сервиса.
• /run гарантированно доступен для записи и предназначен именно для runtime-данных.
• Директива RuntimeDirectory=pgadmin4 автоматически создаёт каталог /run/pgadmin4 с нужными правами при старте сервиса и удаляет его при остановке. Это избавляет от ручного создания каталога и не требует обхода очистки /run после перезагрузки.

5.3. Дать Nginx доступ к сокету

Nginx работает под пользователем www-data, а сокет принадлежит pgadmin. Чтобы Nginx мог подключиться к сокету, добавьте www-data в группу pgadmin:

sudo usermod -aG pgadmin www-data

Права RuntimeDirectoryMode=0750 означают, что владелец (pgadmin) имеет полный доступ, а группа (pgadmin) — чтение и выполнение. Этого достаточно для подключения к сокету.

5.4. Запуск сервиса

sudo systemctl daemon-reload
sudo systemctl start pgadmin4
sudo systemctl enable pgadmin4
sudo systemctl status pgadmin4

Если статус active (running), Gunicorn успешно запущен и слушает Unix-сокет /run/pgadmin4/pgadmin4.sock.

---

Шаг 6. Настройка Nginx

Создайте отдельный конфигурационный файл для pgAdmin:

sudo nano /etc/nginx/sites-available/pgadmin

Содержимое:

server {
    listen 80;
    server_name _;

    # Перенаправляем /pgadmin4 на /pgadmin4/ (важно для корректной работы путей)
    location = /pgadmin4 {
        return 301 /pgadmin4/;
    }

    location ^~ /pgadmin4/ {
        # Проксируем на сокет, который слушает Gunicorn
        proxy_pass http://unix:/run/pgadmin4/pgadmin4.sock;

        # Ключевой заголовок: сообщаем pgAdmin, что он находится в /pgadmin4
        proxy_set_header X-Script-Name /pgadmin4;

        # Используем $http_host, чтобы избежать проблем с редиректами
        proxy_set_header Host $http_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;

        # Настройки для корректной работы WebSocket и таймаутов
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300;
        proxy_connect_timeout 60;
    }
}

Если у вас уже есть работающий сайт, не создавайте отдельный server-блок. Вместо этого добавьте location-блоки в конфигурацию существующего виртуального хоста вашего домена.

Активируйте сайт и перезагрузите Nginx:

sudo ln -s /etc/nginx/sites-available/pgadmin /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

---

Проверка

Откройте браузер и перейдите по адресу:

http://your-domain.com/pgadmin4/

Используйте email и пароль, указанные на шаге 4.

---

Обновление pgAdmin

source /opt/pgadmin4/venv/bin/activate
pip install --upgrade pgadmin4
sudo systemctl restart pgadmin4

---

Диагностика

Логи сервиса:

sudo journalctl -u pgadmin4 -f

Логи Nginx:

sudo tail -f /var/log/nginx/error.log

Проверка сокета:

sudo ls -la /run/pgadmin4/

Ожидаемый вывод: сокет pgadmin4.sock с владельцем pgadmin:pgadmin и правами srwxr-x---.

Проверка, что Nginx видит сокет:

sudo -u www-data test -r /run/pgadmin4/pgadmin4.sock && echo "OK" || echo "Нет доступа"

Типичные ошибки:

Ошибка	Причина	Решение
status=217/USER	Пользователь в User= не существует	Создайте пользователя или укажите root
502 Bad Gateway	Nginx не может подключиться к сокету	Проверьте права на /run/pgadmin4/ и наличие www-data в группе pgadmin
Пустая страница / нет стилей	Не передан X-Script-Name	Убедитесь, что заголовок X-Script-Name /pgadmin4 присутствует
Connection refused	Gunicorn не запущен	Проверьте systemctl status pgadmin4

---

Итог

Схема полностью автономна, не требует Apache и легко обновляется через pip install --upgrade pgadmin4 внутри venv. Использование RuntimeDirectory в systemd гарантирует, что каталог для сокета создаётся и очищается автоматически, а сокет не зависит от очистки /tmp.