PostgreSQL в Docker Compose: пошаговая инструкция
PostgreSQL в Docker Compose поднимается одним файлом compose.yaml и командой docker compose up -d. Данные хранятся в именованном томе, порт публикуется только на localhost, а подключение проверяется через psql внутри контейнера.
01Проверьте Docker и Compose
Docker Compose v2 это плагин, команда пишется через пробел: docker compose. Старый docker-compose не поддерживается с 2023 года. Если Docker ещё не установлен, его ставят из репозитория Docker пакетами docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin и docker-compose-plugin.
docker --version
docker compose version
02Создайте каталог проекта и файл compose.yaml
Создайте отдельный каталог под проект, чтобы имя проекта и тома не пересекались с другими. Файл называйте compose.yaml: это имя по умолчанию, старое docker-compose.yml тоже читается. Ключ version: в начале файла в Compose v2 устарел и даёт только предупреждение, поэтому его не пишут.
mkdir -p ~/pg-app
cd ~/pg-app
nano compose.yaml
03Опишите сервис postgres в compose.yaml
Сервис db использует официальный образ postgres:16. Пароль задаётся через переменную POSTGRES_PASSWORD, данные лежат в именованном томе pgdata. Порт публикуется как 127.0.0.1:5432:5432, чтобы база была доступна только с самого сервера: опубликованные порты Docker обходят UFW.
services:
db:
image: postgres:16
container_name: pg-app-db
restart: unless-stopped
environment:
POSTGRES_PASSWORD: examplepass
POSTGRES_DB: appdb
ports:
- "127.0.0.1:5432:5432"
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d appdb"]
interval: 10s
timeout: 5s
retries: 5
volumes:
pgdata:
04Проверьте конфигурацию
docker compose config проверяет файл и печатает итоговый конфиг. Ошибки YAML видны здесь же, например yaml: line 12: did not find expected key. Отступы делают пробелами, не табуляцией.
docker compose config
05Запустите контейнер
Команда docker compose up -d скачивает образ и запускает сервис в фоне. Если порт 5432 на хосте уже занят, появится Bind for 0.0.0.0:5432 failed: port is already allocated. Кто держит порт, показывает sudo ss -ltnp.
docker compose up -d
docker compose ps
06Подключитесь к базе через psql
Зайдите в контейнер и запустите psql от пользователя postgres. База appdb создана переменной POSTGRES_DB. Внутри сети проекта другие сервисы видят базу по имени сервиса db:5432, а не по localhost.
docker compose exec db psql -U postgres -d appdb
07Проверьте работу базы
В psql выполните SELECT version(); и \l, чтобы увидеть список баз. Команда pg_isready подтверждает готовность сервера. Выход из psql это \q.
docker compose exec db pg_isready -U postgres -d appdb
docker compose exec db psql -U postgres -d appdb -c "SELECT version();"
Частые ошибки
-
В
compose.yamlуказан порт5432:5432, иdocker compose up -dпадает сBind for 0.0.0.0:5432 failed: port is already allocated.Порт на хосте уже занят другой базой или контейнером. Найдите процесс через
sudo ss -ltnpи либо остановите его, либо публикуйте порт как127.0.0.1:5433:5432. -
docker compose up -dпишетpermission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.Пользователь не в группе
dockerили не вошёл заново послеsudo usermod -aG docker $USER. Выполните команду и перезайдите по SSH. Группаdockerравна правам root на сервере. -
docker compose up -dотвечаетno configuration file provided: not found.В текущем каталоге нет
compose.yamlилиdocker-compose.yml. Перейдите в каталог проекта или укажите путь через-f /path/to/compose.yaml. -
После
docker compose downданные в базе пропали.Именованные тома переживают
docker compose down, удаляет их толькоdocker compose down -v. Не запускайте команду с-v, если данные нужны.
Deploykin
Как это делается в Deploykin
В Deploykin Docker-контейнеры создаются, запускаются и останавливаются из панели. Там же видны их статусы и тома, терминал для этого не нужен.
7 дней бесплатно на тарифе Про, без привязки карты.
Вопросы и ответы
Как подключиться к Postgres из другого контейнера в том же compose-проекте?
По имени сервиса: хост db, порт 5432. Сервисы одного проекта видят друг друга в сети <проект>_default, адрес localhost внутри контейнера указывает на него самого.
Где хранятся данные Postgres в Docker Compose?
В именованном томе pgdata, который описан в compose.yaml и подключён к /var/lib/postgresql/data. Том переживает docker compose down и удаляется командой docker compose down -v.
Почему контейнер Postgres завершается с кодом 137?
Код выхода 137 значит, что процесс убит сигналом SIGKILL, чаще всего из-за нехватки памяти. Проверьте docker compose logs db и лимиты памяти на сервере.
Нужен ли ключ version в compose.yaml для Postgres?
Нет. В Compose v2 ключ version: устарел и вызывает только предупреждение. Файл начинают сразу с services:.
Ещё по теме
- Руководство · Docker docker images: работа с образами Docker на Ubuntu 24.04 Как работать с docker images на Ubuntu 24.04: проверить демон, скачать образ через docker pull, посмотреть список, запустить контейнер и проверить результат.
- Руководство · Docker Установка Docker и Docker Compose на Ubuntu 24.04 Пошаговая установка Docker и Docker Compose на Ubuntu 24.04: команды, настройка compose.yaml, проверка работы и разбор частых ошибок.
- Руководство · Docker Как запустить Docker container на Ubuntu 24.04: пошаговая инструкция Запустите контейнер через docker compose up -d, проверьте статус, посмотрите логи, войдите в контейнер через exec и остановите проект. Команды и проверка.
- Руководство · Docker Установка Portainer на Ubuntu 24.04: пошаговая настройка Установите Portainer в Docker Compose на Ubuntu 24.04: проверка Docker, compose-файл, запуск, доступ к панели и проверка через curl и docker compose ps.
- Руководство · Docker Docker volumes: настройка и проверка на Ubuntu 24.04 Пошаговая настройка docker volumes на Ubuntu 24.04: создание тома, подключение к контейнеру, проверка сохранности данных после перезапуска и типичные ошибки.
- Руководство · Docker Установка GitLab в Docker на Ubuntu 24.04 Установите GitLab в Docker на Ubuntu 24.04: подготовка, compose-файл, запуск, проверка и типичные ошибки с командами.
Docker Compose: руководство по работе с многоконтейнерными приложениями: все материалы темы