В этом руководстве установим Coolify на VPS и развернём тестовое приложение напрямую из Git-репозитория. Затем настроим домен, HTTPS, переменные окружения, автоматический деплой после push, постоянное хранилище, просмотр логов, обновление и резервное копирование самой панели Coolify.
В процессе:
- Установим Coolify на Ubuntu VPS;
- Создадим проект и подключим GitHub-репозиторий;
- Выполним первый deployment приложения;
- Привяжем домен и настроим SSL;
- Добавим переменные окружения;
- Подключим persistent storage;
- Настроим автоматический redeploy после push в репозиторий;
- Проверим deployment- и runtime-логи;
- Разберём обновление Coolify;
- Настроим резервное копирование конфигурации платформы.
В результате получим self-hosted PaaS-платформу, через которую приложение можно собирать, публиковать и обновлять из Git без ручного запуска Docker-контейнеров после каждого изменения.
Что будем разворачивать
В этом руководстве установим Coolify на отдельный VPS и используем его как self-hosted платформу для развёртывания приложения из Git-репозитория. Coolify возьмёт на себя сборку приложения, запуск контейнеров, маршрутизацию HTTP/HTTPS, управление переменными окружения, логами и последующими deployment'ами.
В качестве примера развернём небольшое тестовое приложение из GitHub. После первого запуска привяжем к нему домен, включим HTTPS, добавим persistent storage и проверим автоматический redeploy после изменения кода в репозитории.
Как будет работать схема
Общая схема выглядит так:
Разработчик отправляет изменения в Git-репозиторий, после чего Coolify получает новую версию исходного кода и запускает очередной deployment.
При включённом Auto Deploy этот процесс можно автоматизировать:
При этом постоянные данные приложения не должны храниться только внутри файловой системы контейнера. Для них подключим отдельное persistent storage, которое сохраняется между пересозданиями контейнера.
Что понадобится для работы
Для выполнения руководства понадобится:
- VPS с Ubuntu 24.04;
- Доступ по SSH с правами sudo;
- Публичный IPv4-адрес;
- Доступные TCP-порты 80 и 443;
- GitHub-аккаунт;
- Git-репозиторий с тестовым приложением;
- Домен или поддомен, который можно направить на VPS;
- несколько гигабайт свободного дискового пространства для Docker-образов, контейнеров и данных Coolify.
Для тестового приложения будем использовать отдельный поддомен. В примерах документации вместо реального публичного адреса VPS будем указывать 203.0.113.10.
Устанавливаем Coolify на VPS
Coolify разворачивается непосредственно на Linux-сервере и использует Docker для запуска самой платформы и приложений. Перед установкой убедимся, что VPS обновлён и на нём нет сервисов, которые уже занимают необходимые веб-порты.
Подготовка сервера
Подключимся к VPS по SSH и обновим установленные пакеты:
sudo apt update
sudo apt upgrade -y
Проверим версию операционной системы: lsb_release -a
Также можно проверить доступную память и свободное место:
free -h
df -h /
Coolify самостоятельно установит и настроит необходимые компоненты, поэтому вручную разворачивать Docker перед использованием официального установщика обычно не требуется.
Если на сервере уже работает Nginx, Apache, Caddy или другой reverse proxy, который занимает порты 80 и 443, перед установкой нужно решить конфликт портов. Для этого руководства используется отдельный чистый VPS.
Запуск официального установочного скрипта
Для установки Coolify запустим официальный скрипт: curl -fsSL https://cdn.coollabs.io/coolify/install.sh | sudo bash
Скрипт проверит окружение, установит необходимые зависимости и развернёт компоненты Coolify.
Мы не рекомендуем автоматический запуск скриптов, загружаемых из интернета - при использовании на боевых условиях скрипт лучше загрузить, проверить, и только после этого запускать.
Процесс может занять несколько минут. После завершения установщик выведет информацию о доступе к панели.
Открыть её можно по адресу, который будет указан установщиком. На первоначальном этапе это может быть адрес сервера с портом панели, например: http://203.0.113.10:8000
В реальной конфигурации вместо документационного IP необходимо использовать фактический публичный адрес VPS.
Первый вход и создание администратора
При первом открытии Coolify предложит создать учётную запись администратора.
Укажите:
- имя администратора;
- email;
- сложный уникальный пароль.
После регистрации откроется основная панель Coolify. Через неё можно создавать проекты, подключать серверы и Git-источники, добавлять приложения и базы данных, отслеживать deployment'ы и управлять настройками самой платформы.
Так как Coolify в нашем случае установлен на том же VPS, локальный сервер можно использовать как хост для последующего deployment приложения.
После первоначальной настройки Coolify готов к работе. Следующим шагом создадим проект и подключим к нему Git-репозиторий с тестовым приложением.
Подключаем Git-репозиторий
После установки Coolify создадим проект и подключим Git-репозиторий с тестовым приложением. В дальнейшем именно из этого репозитория платформа будет получать исходный код для сборки и последующих deployment'ов.
Создание проекта и окружения
В панели Coolify откройте раздел Projects и создайте новый проект.
Например: Project name: coolify-demo
Внутри проекта создайте окружение: Environment: production
Окружения позволяют разделять разные варианты одного приложения, например production, staging и development.
После создания проекта откройте его и добавьте новый ресурс типа Application.
Подключение GitHub или GitLab
Coolify может получать код из GitHub, GitLab и других Git-источников.
Для GitHub можно использовать интеграцию через GitHub App. Такой вариант удобен тем, что Coolify получает доступ только к разрешённым репозиториям и может автоматически получать события о новых push.
В панели Coolify выберите GitHub как источник приложения и пройдите подключение аккаунта.
Во время настройки GitHub может запросить разрешение установить Coolify GitHub App и выбрать репозитории, к которым она получит доступ.
Для тестового проекта достаточно разрешить доступ только к конкретному репозиторию.
Для GitLab принцип аналогичный: Coolify получает доступ к репозиторию и использует его как источник для deployment.
Если репозиторий публичный и сложная интеграция не требуется, в некоторых сценариях можно использовать обычный Git URL. Однако для дальнейшей демонстрации Auto Deploy удобнее использовать полноценную интеграцию с GitHub.
Выбор репозитория и ветки
После подключения Git-источника выберите тестовый репозиторий.
Например:
Repository: coolify-demo
Branch: main
Coolify будет использовать указанную ветку как источник production-версии приложения.
Если проект находится не в корне репозитория, дополнительно можно указать рабочую директорию. Для простого тестового приложения оставим корень репозитория: Base Directory: /
Разворачиваем тестовое приложение
Теперь настроим способ сборки и выполним первый deployment.
Coolify может самостоятельно определить технологию приложения либо использовать явно заданный способ сборки. Конкретный вариант зависит от содержимого репозитория.
Настройка способа сборки
Для обычного приложения без собственного Dockerfile можно использовать Nixpacks. Coolify анализирует содержимое репозитория, определяет язык и зависимости, после чего формирует окружение для сборки.
Например, для небольшого Node.js-приложения репозиторий может содержать:
package.json
package-lock.json
server.js
В package.json должен быть определён способ запуска:
{
"scripts": {
"start": "node server.js"
}
}
Приложение должно слушать не только localhost, а интерфейс контейнера. Например: app.listen(process.env.PORT || 3000, '0.0.0.0');
В Coolify укажем внутренний порт приложения: Ports Exposes: 3000
Если в репозитории уже присутствует Dockerfile, вместо Nixpacks можно выбрать сборку непосредственно по нему. Это даёт больше контроля над образом и процессом запуска.
Для нашего демонстрационного приложения достаточно автоматической сборки через Nixpacks.
Первый Deploy
После настройки Git-источника и способа сборки нажмите Deploy.
Coolify последовательно:
- Получит исходный код из репозитория;
- Подготовит окружение сборки;
- Установит зависимости;
- Соберёт приложение;
- Создаст и запустит контейнер;
- Подключит его к внутренней сети и reverse proxy.
Прогресс можно отслеживать непосредственно в deployment logs.
При успешном завершении deployment получит статус вроде: Deployment successful
или приложение перейдёт в состояние: Running
Если сборка завершается ошибкой, в первую очередь стоит проверить deployment logs. Частые причины — отсутствующая команда запуска, неправильный внутренний порт, ошибка установки зависимостей или несовместимая версия runtime.
Проверка приложения
После успешного deployment Coolify может предоставить временный адрес приложения либо адрес, настроенный через proxy.
Откройте его в браузере.
Для тестового проекта достаточно простой страницы, например:
Coolify Demo
Application deployed successfully from Git.
Если страница открывается, значит вся основная цепочка уже работает.
Настраиваем домен и HTTPS
После первого успешного deployment приложение уже работает внутри инфраструктуры Coolify. Теперь привяжем к нему собственный домен и включим HTTPS, чтобы пользователи могли обращаться к сервису по привычному адресу без указания технического порта.
DNS-запись для приложения
Сначала создадим DNS-запись у регистратора домена или DNS-провайдера.
Для поддомена app.example.com понадобится запись типа A:
Type: A
Name: app
Value: 203.0.113.10
Здесь 203.0.113.10 — пример публичного IPv4-адреса VPS. В реальной конфигурации необходимо указать фактический адрес сервера, на котором установлен Coolify.
Если используется корневой домен, поле имени записи у разных DNS-провайдеров может обозначаться как @ или оставляться пустым.
После сохранения записи потребуется дождаться обновления DNS. Проверить результат можно командами dig +short app.example.com или nslookup app.example.com
Домен должен разрешаться в публичный IP сервера Coolify.
Добавление домена в Coolify
Откройте приложение в Coolify и перейдите к его основным настройкам.
В поле домена укажите полный адрес, например: https://app.example.com
Coolify использует встроенный reverse proxy для маршрутизации запросов к нужному приложению. Поэтому нескольким сервисам на одном VPS не требуется публиковать собственные HTTP-порты напрямую в интернет, а также нет необходимости настраивать прокси врод Nginx/
После сохранения настройки запрос к:
будет направляться reverse proxy к контейнеру приложения и его внутреннему порту.
Перед выпуском сертификата DNS-запись уже должна указывать на сервер, а входящие подключения к портам 80 и 443 должны быть разрешены на уровне облачного firewall или security group.
Автоматическое получение SSL-сертификата
При использовании домена с HTTPS Coolify может автоматически получить TLS-сертификат и подключить его к reverse proxy.
Для этого необходимо, чтобы:
- Домен корректно указывал на VPS;
- Сервер был доступен из интернета;
- Порты 80 и 443 не блокировались firewall;
- Другой сервис на сервере не занимал порты reverse proxy.
После успешной настройки приложение станет доступно по адресу: https://app.example.com
Браузер должен показывать защищённое HTTPS-соединение.
Сертификат в дальнейшем обновляется автоматически, поэтому вручную запускать Certbot для каждого приложения обычно не требуется.
Добавляем переменные окружения
Приложениям часто требуется конфигурация, которая отличается между development, staging и production: адреса API, режим работы, названия сервисов, параметры подключения к базам данных и ключи внешних систем.
Хранить такие значения непосредственно в исходном коде неудобно. Coolify позволяет задавать их через Environment Variables и передавать приложению при сборке или запуске.
Runtime-переменные
Откройте приложение и перейдите в раздел Environment Variables.
Добавим несколько простых параметров:
APP_NAME=Coolify Demo
APP_ENV=production
После сохранения эти значения можно получить внутри приложения стандартными средствами используемого языка.
Например, в Node.js:
const appName = process.env.APP_NAME;
const appEnv = process.env.APP_ENV;
Так один и тот же код можно использовать в нескольких окружениях, меняя только конфигурацию в Coolify.
В зависимости от типа приложения часть переменных может потребовать нового deployment, чтобы изменённые значения попали в контейнер.
Секретные значения
Через Environment Variables можно передавать и чувствительные параметры, например:
DATABASE_URL
API_KEY
JWT_SECRET
Такие значения не следует записывать непосредственно в Git-репозиторий.
Например, вместо: const apiKey = "my-secret-key";
приложение получает значение из окружения: const apiKey = process.env.API_KEY;
Это позволяет хранить исходный код и конфигурацию отдельно и использовать разные секреты для разных окружений.
Для тестового приложения можно оставить обычные демонстрационные значения:
APP_NAME=Coolify Demo
APP_ENV=production
После изменения переменных выполним redeploy приложения и проверим, что новая конфигурация применяется внутри контейнера.
Переменные окружения позволяют менять конфигурацию приложения без внесения соответствующих значений непосредственно в исходный код и являются особенно удобными при использовании автоматического deployment из Git.
Настраиваем постоянное хранилище
Контейнеры приложений в Coolify могут пересоздаваться во время нового deployment, обновления конфигурации или ручного перезапуска. Поэтому данные, которые должны сохраняться независимо от жизненного цикла контейнера, необходимо вынести в persistent storage.
Зачем приложению persistent storage
Файлы, созданные только внутри файловой системы контейнера, могут быть потеряны после его пересоздания.
Это особенно важно для приложений, которые хранят:
- Загруженные пользователями файлы;
- Локальные базы данных;
- Генерируемый контент;
- Кеш, который необходимо сохранять;
- Конфигурационные или служебные файлы.
Для таких данных Coolify позволяет подключать постоянное хранилище к определённому пути внутри контейнера.
Например, тестовое приложение может записывать данные в каталог: /app/data
Без создания persistent storage этот каталог относится к файловой системе текущего контейнера. После redeploy новый контейнер может получить пустой каталог.
С подключённым volume схема меняется:
Контейнер можно заменить, а данные останутся в отдельном Docker volume.
Создание Docker volume
Откройте настройки приложения в Coolify и перейдите в раздел Storages или Persistent Storage.
Создайте новое хранилище и укажите путь назначения внутри контейнера: Destination Path: /app/data
Для Docker volume можно задать отдельное имя, например: coolify-demo-data
После сохранения Coolify подключит volume к контейнеру приложения.
Для приложения это будет выглядеть как обычный каталог /app/data, однако фактически содержимое будет храниться непосредственно на нашей VPS, отдельно от файловой системы контейнера.
Если приложение использует другой каталог для постоянных данных, в качестве destination необходимо указать именно его. Например, для загрузок это может быть /app/uploads, а для некоторых приложений — собственный каталог данных, определённый разработчиком.
Проверка сохранения данных после redeploy
Проверим, что persistent storage действительно переживает пересоздание приложения.
Сначала приложение должно создать тестовый файл в подключённом каталоге, например: /app/data/persistent.txt
Содержимое может быть простым: Persistent storage is working.
После этого выполним новый deployment приложения.
Coolify соберёт новую версию и заменит работающий контейнер, но подключит к нему тот же volume.
После завершения redeploy проверим наличие файла. Если persistent.txt по-прежнему доступен, значит данные находятся за пределами временной файловой системы контейнера и сохраняются между deployment'ами.
Persistent storage при этом не заменяет резервное копирование. Удаление самого volume, сбой диска или потеря VPS могут привести к потере данных, поэтому важные volumes необходимо резервировать отдельно.
Настраиваем автоматический деплой после push
Постоянно запускать новый deployment вручную после каждого изменения в Git необязательно. Coolify может получать уведомление от Git-провайдера и автоматически разворачивать новую версию приложения после push в выбранную ветку.
Как работает Auto Deploy
После настройки автоматического deployment процесс выглядит так:
Coolify получает событие об изменении репозитория, загружает актуальное состояние выбранной ветки и запускает тот же процесс сборки, который использовался при первом deployment.
Так production-версия приложения может автоматически следовать за веткой main.
Для более сложных проектов вместо непосредственного deployment после каждого push можно использовать отдельные ветки, staging-окружение или CI/CD-проверки перед публикацией.
Настройка GitHub App или webhook
Если репозиторий подключён через GitHub App, Coolify может использовать события GitHub для запуска новых deployment'ов.
В настройках приложения включите автоматический deployment для выбранной ветки:
Branch: main
Auto Deploy: Enabled
После этого изменения в main будут использоваться как источник новой версии приложения.
Для других Git-источников аналогичную схему можно реализовать через webhook. Git-провайдер отправляет HTTP-запрос в Coolify после появления нового commit, а платформа запускает deployment соответствующего приложения.
Webhook удобен и в тех случаях, когда репозиторий подключён обычным Git URL, но требуется автоматизировать обновление.
Изменение приложения и push
Для проверки Auto Deploy изменим содержимое тестовой страницы.
Например, первоначально приложение выводило:
Coolify Demo
Application deployed successfully from Git.
Изменим вторую строку:
Coolify Demo
Application automatically redeployed after push.
Зафиксируем изменение:
git add .
git commit -m "Test Coolify auto deploy"
git push origin main
После push Coolify должен получить событие от GitHub и создать новый deployment без ручного нажатия кнопки Deploy.
В истории deployment'ов появится новый запуск, связанный с последним commit.
После завершения сборки откроем приложение ещё раз. Если отображается обновлённый текст, цепочка push → webhook → build → deploy работает корректно.
Автоматический deployment особенно удобен для небольших проектов и непрерывной доставки, поскольку сервер самостоятельно получает и разворачивает изменения из Git-репозитория.
Просматриваем логи приложения
После deployment полезно проверить не только статус контейнера, но и его логи. Они помогают понять, как прошла сборка, успешно ли запустилось приложение и не возникают ли ошибки уже во время работы.
В Coolify логи можно просматривать непосредственно через веб-интерфейс, поэтому для базовой диагностики не обязательно подключаться к VPS и вручную искать нужный Docker-контейнер.
Deployment Logs
Deployment Logs относятся непосредственно к процессу развёртывания.
В них отображаются этапы:
- Получение исходного кода;
- Подготовка окружения сборки;
- Установка зависимостей;
- Выполнение build-команд;
- Создание образа;
- Запуск новой версии приложения.
При успешном deployment в конце журнала будет видно, что сборка завершилась и новая версия приложения была запущена.
Если deployment завершается ошибкой, этот журнал стоит проверять в первую очередь. Например, здесь можно увидеть отсутствующую зависимость, неверную команду сборки или проблему при создании Docker-образа.
Для каждого нового deployment Coolify сохраняет отдельный журнал, поэтому можно сопоставлять ошибки с конкретными изменениями в Git.
Runtime Logs
Deployment может завершиться успешно, но ошибка возникнуть уже после запуска приложения. Для таких ситуаций используются Runtime Logs.
Они содержат стандартный вывод работающего контейнера — то, что приложение записывает в stdout и stderr.
Например, Node.js-приложение может при запуске вывести:
Coolify Demo started
Environment: production
Listening on port 3000
Если приложение завершается с ошибкой или не может подключиться к внешнему сервису, соответствующие сообщения также появятся в runtime-логе.
Поэтому эти два вида журналов решают разные задачи:
Deployment Logs → сборка и развёртывание
Runtime Logs → работа уже запущенного приложения
При диагностике проблемы сначала стоит определить, на каком этапе она возникла. Если новая версия вообще не разворачивается — изучить Deployment Logs. Если deployment успешен, но приложение работает неправильно — перейти к Runtime Logs.
Обновляем и резервируем Coolify
Coolify управляет приложениями и частью инфраструктуры сервера, поэтому саму платформу также необходимо поддерживать в актуальном состоянии и резервировать её конфигурацию.
Обновление Coolify и backup пользовательских приложений при этом являются разными задачами. Резервная копия самой платформы не должна рассматриваться как замена резервному копированию баз данных и persistent volumes приложений.
Проверка и установка обновлений
Coolify поддерживает обновление установленного экземпляра через собственный интерфейс.
Информацию о текущей версии и доступном обновлении можно проверить в настройках Coolify. Если новая версия доступна, платформу можно обновить из панели.
Перед обновлением рабочей системы желательно проверить changelog новой версии и убедиться, что резервные копии актуальны.
Обновление самой платформы не требует повторной установки всех приложений вручную: Coolify сохраняет их конфигурацию и продолжает управлять созданными ресурсами после обновления.
Для критичной инфраструктуры обновления лучше сначала проверять на тестовом окружении или устанавливать в запланированное окно обслуживания.
Автоматические обновления
Coolify позволяет автоматизировать обновление самой платформы.
Это удобно для небольших серверов, где не требуется вручную контролировать установку каждой новой версии. Однако полностью автоматическое применение обновлений подходит не для всех production-систем.
На сервере с критичными приложениями безопаснее разделять две задачи:
- Автоматически проверять наличие новых версий;
- Устанавливать обновления вручную после проверки изменений.
Так можно заранее ознакомиться с release notes и выбрать подходящее время для обслуживания.
Если инфраструктура допускает автоматические обновления, их можно оставить включёнными и регулярно контролировать состояние приложений после установки новой версии.
Создание резервной копии Coolify
Coolify хранит собственную конфигурацию, информацию о проектах, ресурсах и другие данные, необходимые для управления экземпляром платформы.
Для восстановления после сбоя необходимо настроить backup этих данных.
Резервную копию лучше хранить не только на том же VPS, где работает Coolify. Локальная копия данных может присутствовать для оперативного восстановления, но при полном отказе диска локальная копия может быть потеряна вместе с основным экземпляром.
Поэтому для backup лучше использовать внешнее хранилище, например S3-совместимое.
Общая схема выглядит так:
В настройках backup необходимо указать параметры удалённого хранилища и расписание создания копий. Частота зависит от того, насколько часто меняется конфигурация платформы.
Важно разделять резервное копирование самого Coolify и размещённых через него сервисов. Backup Coolify нужен для восстановления конфигурации платформы, но постоянные данные приложений требуют собственной стратегии резервного копирования.
Например:
Заключение
Coolify позволяет превратить обычный VPS в self-hosted платформу для развёртывания приложений из Git-репозиториев без необходимости вручную собирать Docker-образы и перезапускать контейнеры после каждого изменения.
В этом руководстве мы установили Coolify, подключили GitHub-репозиторий, выполнили первый deployment, настроили домен и HTTPS, добавили переменные окружения и persistent storage. Затем включили автоматический deployment после push, проверили deployment- и runtime-логи, а также рассмотрели обновление и резервное копирование самой платформы.
Для рабочего окружения важно отдельно продумать резервное копирование данных приложений. Backup Coolify помогает восстановить конфигурацию платформы, но базы данных, Docker volumes и пользовательские файлы требуют собственной стратегии резервного копирования.
FAQ
Можно ли развернуть через Coolify несколько приложений на одном VPS?
Да. В Coolify можно создавать несколько проектов и ресурсов, каждый из которых будет развёрнут в отдельном контейнере или наборе контейнеров.
Для каждого приложения можно использовать собственный домен, переменные окружения, persistent storage и отдельный Git-репозиторий.
Обязательно ли использовать GitHub?
Нет. Coolify поддерживает не только GitHub, но и другие Git-источники, включая GitLab и обычные Git-репозитории.
Конкретный способ подключения зависит от того, где хранится исходный код и нужен ли автоматический deployment после изменений.
Нужен ли Dockerfile?
Не всегда. Coolify может собирать многие приложения автоматически, например с помощью Nixpacks.
Если проекту требуется нестандартное окружение или полный контроль над процессом сборки, можно добавить собственный Dockerfile.
Как Coolify получает SSL-сертификат?
После привязки домена Coolify использует reverse proxy и автоматически выпускает TLS-сертификат Let's Encrypt, при корректно настроенном DNS и доступных портах 80 и 443.
После этого приложение становится доступно по HTTPS, а обновление сертификата выполняется автоматически.
Что произойдёт после push в GitHub?
Если Auto Deploy включён и интеграция с GitHub настроена корректно, Coolify получит событие о новом commit и запустит новый deployment.
Платформа загрузит актуальную версию ветки, соберёт приложение и заменит работающий контейнер новой версией.
Сохраняются ли файлы приложения после redeploy?
Только если они находятся в persistent storage.
Данные, записанные исключительно во временную файловую систему контейнера, могут быть потеряны при его пересоздании. Для постоянных файлов следует использовать Docker volume или другое поддерживаемое хранилище.
Где смотреть ошибки deployment?
Ошибки сборки и deployment отображаются в Deployment Logs.
Если приложение успешно развернулось, но работает неправильно уже после запуска, следует проверить Runtime Logs.
Нужно ли включать автоматическое обновление Coolify?
Это зависит от требований инфраструктуры. Для небольших проектов автоматические обновления могут быть удобны.
Для production-систем часто безопаснее автоматически проверять наличие новых версий, но устанавливать их вручную после проверки changelog и создания актуального backup.
Резервирует ли backup Coolify данные приложений?
Не обязательно. Резервная копия Coolify предназначена прежде всего для восстановления конфигурации самой платформы.
Базы данных, Docker volumes, пользовательские загрузки и другие persistent-данные следует резервировать отдельно.
