❯ Введение
Coolify — это инструмент с открытым исходным кодом, который позволяет легко устанавливать на своём сервере разные приложения: сайты, базы данных, сервисы, скрипты, боты и остальное.
В прошлых статьях о Coolify мы уже разобрали важные вопросы:
Ожидаем, что вы уже прочитали эти статьи и прошли все описанные в них этапы.
Это значит, что теперь мы можем перейти к деплою (установке) приложений на сервере.
❯ Что такое Ресурсы и каких типов они бывают
Сначала разберёмся с некоторыми важными понятиями, которые используются в Coolify.
Ресурс (Resource) в Coolify это одно из трёх:
Приложение (Application)
База данных (Database)
Сервис (Services)
Приложение (Application) это то, что будет установлено из указанного вами источника, например репозитория с кодом. Это может быть что угодно, в том числе сайт, скрипт, бот и т. д.
При этом приложением может быть и любая база данных. А также приложением может быть какой-то сложный сервис с открытым исходным кодом, вроде n8n или Supabase.
Однако Coolify предлагает специальные типы ресурсов для этих случаев: Базы данных (Database) и Сервисы (Services). Т.е. можно почти в один клик установить базу данных, например PostgresSQL, MySQL, MongoDB. А также можно максимально легко установить open source программу, вроде n8n, Supabase, NocoDB, Plex, Directus и многое другое. Полный список поддерживаемых сервисов можно посмотреть в документации Coolify.
Сегодня мы будем рассматривать только установку Приложений. Сначала по шагам разберёмся, как это происходит в целом, а затем проверим на конкретных примерах.
❯ Деплой (установка) приложения
Шаг 1. Подготовка репозитория
Есть разные способы деплоя приложений в Coolify, и основной — из репозитория с кодом.
Репозиторий — это хранилище кода проекта. Для управления своими репозиториями онлайн есть специальные сайты, например GitHub или GitLab. Код нужного проекта может лежать прямо в корне репозитория, или же в одной из папок внутри.
Для деплоя можно использовать общедоступный репозиторий, который открыт для всех. Например, набор демо-проектов, подготовленный разработчиками Coolify. Чтобы установить приложение из такого репозитория, достаточно просто иметь ссылку на него.
Если же у вас свой собственный проект, то вам сначала нужно выгрузить его на GitHub или другой аналогичный сайт. В этой статье мы не будем останавливаться на том, как это это сделать.
При этом вы можете сделать свой репозиторий открытым и использовать эту общедоступную ссылку для дальнейшей установки проекта из Coolify. Но чаще всего вы не захотите так делать. Как минимум, чтобы никто посторонний не увидел ваш проект.
Вместо этого вы можете создать закрытый репозиторий. Чтобы ставить приложения из него, Coolify сначала должен получить к нему доступ. В следующих шагах мы рассмотрим, как это сделать.
И нужно рассмотреть ещё один сценарий — когда вы хотите создать личную копию общедоступного репозитория. Позже станет понятно, почему это бывает полезно. На сайте GitHub для этого проще всего использовать функцию импорта репозитория. Вот как она работает:
Открываем страницу импорта.
В поле «The URL for your source repository» вставляем url репозитория целиком, например
https://github.com/coollabsio/coolify-examples.Поля «Your username» и «Your access token» пропускаем.
В поле «Repository name» вписываем желаемое имя нашей копии репозитория. Например
coolify-examples-copy.Выбираем режим видимости — общедоступный («Public») или личный закрытый («Private»).
Нажимаем «Begin Import». Импорт может идти несколько минут, и после этого вы получите копию исходного репозитория в вашем аккаунте.
Шаг 2. Открытие в GitHub App доступа к репозиторию (если нужно)
Если для проекта вы используете общедоступный репозиторий, то этот шаг можно пропустить.
Если же у вас закрытый личный репозиторий, то сначала нужно сделать так, чтобы у Coolify был к нему доступ. В случае с GitHub это можно сделать через GitHub App. Что это такое, и как это настроить, мы разбирали в прошлой части.
Как вы помните из той статьи, у нас возможны два варианта:
Если у вас настроен в GitHub App глобальный доступ, то для Coolify всегда открыты все ваши репозитории. Тогда на этом шаге делать ничего не нужно.
Если же у вас настроен выборочный доступ, то для каждого нового проекта надо открывать доступ к нужному репозиторию.
Напомним, как открывать доступ в GitHub App, если это потребуется:
В Coolify переходим в Sources (источники) и выбираем нужный источник, чтобы открыть его настройки.
На странице настроек нажимаем на ссылку Update Repository сверху справа.
Откроется страница GitHub. Скорее всего, для авторизации нам нужно будет ввести пароль.
Попадаем на страницу настроек этого GitHub App. В блоке «Repository access» нажимаем на выпадающий список «Select repositories» и выбираем нужный репозиторий. Он появится в списке.
Не забудьте нажать «Save», чтобы сохранить изменения. Теперь доступ к нужному репозиторию открыт.
После этого вы будете перенаправлены обратно в Coolify.
На момент написания статьи на последнем шаге был баг, что ссылка на админку дается в виде IPv4-адреса, а не доменного имени. Поэтому перенаправление не работает так, как хотелось бы, и надо просто самому снова открывать страницу админки.
Шаг 3. Создание проекта и ресурса
Для создания нового ресурса:
Переходим в пункт Проекты (Projects) в меню. Проекты используются в Coolify, чтобы логически группировать ресурсы.
Выбираем один из существующих проектов или создаем новый (кнопка «Add»).
Внутри проекта видим список его ресурсов. Нажимаем «+ New».
Также, у каждого проекта может быть от одного до нескольких Окружений (Environments). По умолчанию у проекта создается одно окружение под названием «production». И для начала его будет достаточно — оно будет выбираться автоматически при создании нового Ресурса.
Шаг 4. Выбор типа ресурса и типа источников
Открывается страница выбора типа ресурса.
На этой странице у нас есть 3 больших блока — под каждый из типов:
Приложение (Application)
База данные (Database)
Сервис (Services)
Сегодня мы рассматриваем только приложения.
Для приложений предлагается несколько вариантов источников, которые разбиты на 2 группы: Git Based (на основе Git) и Docker Based (на основе Docker)
В группе Git Based предлагаются варианты, когда код берется из репозитория:
Public Repository — общедоступный репозиторий, который доступен для всех по ссылке. Это может быть ссылка на GitHub или на другого провайдера.
Private Repository with GitHub App — приватный репозиторий GitHub, который принадлежит вам, или к которому у вашего аккаунта есть доступ. Нужно настраивать подключение через GitHub App.
Private Repository with Deploy Key — приватный репозиторий, доступ к которому предоставляется по ключу. Это может быть не только GitHub, но и другой провайдер.
А варианты в группе Docker Based не связаны с репозиториями. Тут приложения или будут созданы через специальные файлы-инструкции (Dockerfile или Docker Compose), или будут скачены из внешнего источника (Docker Image).
Из-за такого разделения может показаться, что в вариантах Git Based технология Docker не задействуется, но это не так:
В любом случае деплой основан на технологии Docker. То есть будет происходить сборка приложений в docker-образы (Docker Image) и запуск их в виде docker-контейнеров.
И в любом случае можно использовать файлы Dockerfile или Docker Compose для сборки приложений, если хочется.
Т. е. разница между «Git Based» и «Docker Based» в том, есть ли репозиторий с кодом, а не в том, используется ли Docker.
В этой статье мы будем рассматривать только «Git Based» — установку из репозитория. Поэтому на данном шаге выбирайте любой подходящий вам вариант из этой группы.
Шаг 5. Выбор сервера
Далее вам нужно будет выбрать сервер. Это может быть «localhost» или отдельный дополнительный сервер, который вы заранее добавили, например «coolify-apps».
Шаг 6. Выбор репозитория
Теперь нужно указать репозиторий. Способ выбора репозитория будет зависеть от того, какой тип источника вы выбрали до этого.
Если до этого вы выбрали Public Repository, то вам будет предложено указать ссылку на него (url). Ссылку можно указать разными способами:
Можно указать только путь до самого репозитория, например
https://github.com/coollabsio/coolify-examples/. Тогда по умолчанию будет выбрана ветка «main».Если же вам нужна другая ветка, то лучше сразу указать ее в пути, например
https://github.com/coollabsio/coolify-examples/tree/v4.x/, где/v4.x— нужная ветка.Если вам нужен не весь репозиторий, а конкретная папка в нём, то можно дополнительно сразу же указать в url путь до папки, например
https://github.com/coollabsio/coolify-examples/tree/v4.x/vue/spa, где/vue/spa— нужная папка.
Если же вы выбрали Private Repository with GitHub App, то сначала вы увидите список настроенных источников (интеграций с Github App) в вашем Coolify, чтобы выбрать нужный. А уже после этого вы увидите список репозиториев, к которым имеет доступ этот Github App. Нужно просто выбрать нужный репозиторий из списка.
А если вы выбрали Private Repository with Deploy Key, то сначала вам нужно будет выбрать из созданных в Coolify SSH-ключей или создать новый. А уже затем ввести адрес репозитория, по аналогии с тем, как описано выше в способе Public Repository.
Шаг 7. Форма создания приложения
Далее появляется форма создания приложения, где заполняются ключевые поля, нужные для деплоя приложения. Отметим, что в процессе заполнения этой формы, когда вы выбираете определённые значения, какие-то поля могут появляться, исчезать или автоматически заполняться нужными значениями.
Рассмотрим поля этой формы. И хотя их можно будет отредактировать на следующем шаге, лучше всего сразу заполнять их корректно.
Ветка репозитория (Branch)
Если у нашего репозитория несколько веток, то нужно выбрать актуальную. Если ветка была указана в ссылке на репозиторий, то её значение само подгрузится в это поле, и на этом шаге сменить её будет нельзя. По умолчанию выбирается ветка «main».
Способ сборки (Build Pack)
Работа с приложениями в Coolify основана на технологии Docker. Напомним: это значит, что создаётся или скачивается docker-образ приложения, а затем этот образ запускается в виде docker-контейнера. Контейнер обеспечивает нужную изоляцию приложения от других программ на сервере.
Процесс создания docker-образа называется его сборкой. И Coolify должен как-то понять, как именно нужно собрать образ из исходного кода.
В этом вопросе Coolify предлагает 4 варианта:
Nixpacks
Static (статичные файлы)
Dockerfile
Docker compose
Dockerfile и Docker Compose
Для описания того, как собирать образы, в экосистеме docker есть специальные типы файлов-инструкций: .dockerfile и docker-compose.yml.
.dockerfileописывает, как собрать один docker-образ, поэтому его будет достаточно для простых приложений.docker-compose.ymlдополнительно описывает, как связать несколько контейнеров между собой — он нужен уже для сложных приложений.
И многие разработчики сами описывают эти файлы и сохраняют их в репозитории вместе с кодом. Это значительно упрощает деплой таких приложений. Поэтому, если вы видите один из этих файлов в репозитории, то значит на этом шаге в поле «Build Pack» лучше просто выбрать «Dockerfile» или «Docker Compose» соответственно.
Nixpacks
Однако не всегда в репозиториях есть готовые файлы для сборок под Docker. И тогда на помощь приходит проект Nixpacks. Это инструмент, который сканирует репозиторий и на основании этого сам готовит Dockerfile, чтобы собрать приложение.
Эта технология работает неидеально: иногда полученные docker-образы получаются неоптимальные (например, много весят) или даже выдают ошибку. Но в большинстве случае это работает. И этот способ может помочь, когда нужно как можно быстрее запустить какой-нибудь несложный проект.
Вместе с этим, с Nixpacks есть проблема — в данный момент активная разработка этого проекта уже не ведётся. И в связи с этим есть некоторые неудобства, о которых мы поговорим дальше. В будущем Coolify перейдёт на другой аналогичный инструмент вместо Nixpacks.
Статичные файлы (Static)
Обычно код, который хранится в репозиториях, это еще не итоговый код приложения и ему требуется предварительная сборка.
Однако иногда бывает, что в репозитории все-таки хранятся уже готовые файлы приложения: страницы, изображения, скрипты и т. д. Например, такое бывает, когда для создания сайта вы используете какой-нибудь онлайн-конструктор, из которого потом экспортируете файлы. Для таких случаев и есть вариант «Static».
Директория в репозитории (Base Directory)
«Base Directory» — это директория (папка) в репозитории, где хранится код вашего приложения. По умолчанию прописано «/», что соответствует ситуации, когда нужный код хранится в корне. Обычно это означает, что в репозитории — один проект.
Но бывает, что в одном репозитории хранится несколько проектов. Это могут быть несвязанные проекты, как например в официальном репозитории Coolify с примерами. Или же это могут быть разные части одного приложения, например backend и frontend — такой подход к хранению кода проекта называется «монорепозиторий» (monorepo).
Поэтому, при необходимости, в поле «Base Directory» указывается путь до нужной папки внутри репозитория, например /templates/nuxt, /vue/spa, /backend, /frontend и т. д.
Если путь уже был указан в ссылке на репозиторий, то значение подгрузится автоматически.
Порт (Ports Exposes)
В блоке «Network» в поле «Port Exposes» указывается порт, который будет использоваться приложением. По умолчанию значение 3000, и для обычных случаев вам можно не менять его.
Статичный ли сайт (Is it a static site?)
Если у вашего приложения нет серверной части, а есть только фронтенд (т.е. это сайты по принципам SPA или SSG), то нужно поставить галочку в поле «Is it a static site?». В таком случае в ваше приложение будет добавлен веб-сервер Nginx, чтобы отдавать нужные файлы. В поле «Ports Exposes» значение поменяется на «80».
Если же у вас бэкенд-приложение или SSR-фреймворк (Next, Nuxt и т. д.), то галочку нужно оставить пустой.
Стоит отметить, что эта галочка это не одно и то же, что и вариант «Static» в блоке выбора варианта деплоя. Смысл здесь похожий — в обоих случаях речь о том, что итоговый сайт это набор готовых файлов, которые отдаются веб-сервером nginx по запросу к соответствующей странице. Однако разница в том, что в данном случае «static» значит, что эти файлы генерируются во время сборки приложения. А «static» в вариантах деплоя означает, что файлы не нужно генерировать — в репозитории они уже изначально в итоговом виде.
Директория с приложением (Publish Directory)
Если поставить галочку «Is it a static site», то появится поле «Publish Directory». При необходимости, тут нужно указать путь в контейнере до сгенерированного кода приложения.
Путь отличается в зависимости от сборщика или фреймворка. Например, для Vite или Vue это обычно папка «/dist».
Шаг 8. Конфигурация ресурса
После создания ресурса открывается раздел его детальных настроек. В этот момент проект еще не запущен.
Этот раздел довольно внушительный — мы видим несколько вкладок сверху, из которых по умолчанию выбрана вкладка Configuration (Конфигурация). А в столбце слева мы видим полтора десятка боковых вкладок — это все разные страницы внутри Конфигурации. Но можно не волноваться — поначалу большинство этих страниц не пригодятся.
По умолчанию мы находимся на странице General — это основные настройки конфигурации ресурса.
Видно, что некоторые поля на этой странице повторяю��ся из тех, что мы заполняли на прошлом шаге. Поэтому, при необходимости, их можно изменить.
Но также на этой странице есть много других важных полей, которые нужно заранее настроить до деплоя проекта. Состав полей отличается в зависимости от того, какой способ сборки вы выбрали до этого. Мы рассматриваем вариант сборки через Nixpacks — в таком случае число возможных полей для настройки будет больше всего.
Имя ресурса (Name)
В поле «Name» показывается имя ресурса. По умолчанию оно генерируется на основе названия репозитория, с добавлением случайных символов в конце. И хотя можно оставить Name по умолчанию, но для удобства лучше сразу поменять его на что-то более понятное и подходящее.
Это SPA-приложение (Is it a SPA — Single Page Application?)
Если у вас установлена галочка «Is it a static site?», то в настройках появится и поле с галочкой «Is it a SPA (Single Page Application)?».
Её нужно выбрать, если у вас SPA-сайт. Их называют «одностраничными», но на самом деле это может быть обычный сайт со множеством страниц. Термин «одностраничный» просто отсылает к особенностям технической реализации таких сайтов.
Если же у вас не SPA, а например SSG-сайт, то галочку ставить не нужно.
Домены (Domains)
Здесь вы указываете один или несколько адресов, по которым будет размещаться ваш сайт.
По умолчанию Coolify уже предлагает случайно сгенерированный вариант, причём:
Если в настройках выбранного сервера в Coolify указан wildcard-домен, то случайный адрес будет по вашему домену, например
https://m08gsww4w0wcgw4oksg8ow8k.ivanivanov.ru.Если же домен не привязан, то будет предложен адрес на домене
sslip.ioи с IPv4-адресом перед ним. Например,http://vcok4wc8s8gw0k848gcgc4g8.123.123.123.123.sslip.io. Этим вариантом можно пользоваться в тестовых целях как временным решением.
И хотя в тестовых целях можно запускать сайт с предложенным по умолчанию временным адресом, но лучше сразу прописать осмысленный url. Например https://vue-demo.ivanivanov.ru.
Напомним, что для того, чтобы данный адрес работал, у вас должны быть настроены DNS. Как это делать, мы разбирали в первой части руководства.
При этом можно указать несколько адресов через запятую без пробелов. И как раз рекомендуется указывать для каждого адреса два варианта: с www и без www. Т. е. например https://vue-demo.ivanivanov.ru,https://www.vue-demo.ivanivanov.ru. Но тогда обязательно нужно выбрать один правильный («каноничный») вариант адреса и включить перенаправление на него (см. далее про поле «Direction»).
Кнопку «Generate Domain» обычно нажимать не требуется — она нужна для генерации случайного адреса, а не для сохранения указанного значения.
Иногда вам не нужен адрес совсем — например, для Telegram-бота или для скрипта, которое просто выполняет какие-то задачи по расписанию. Но на момент написания статьи в Coolify есть баг, что если оставить поле домена пустым, то происходит ошибка при сборке. Если вы с этим столкнулись, то можно просто написать в домене что угодно, например продублировать там значение поля «Name». Главное, чтобы значение было и оно было уникальным по отношению к другим вашим ресурсам.
Настройка перенаправлений www (Direction)
Через эту настройку определяется поведение адресов с www и без www. Например, https://demo.ivanivanov.ru и https://www.demo.ivanivanov.ru.
По умолчанию выбран вариант «Allow www & non-www», т. е. оба адреса открываются без перенаправлений.
Но лучше выбрать опцию «Redirect to non-www» — тогда адреса с «www» будут перенаправляться на зеркальные адреса без «www». При этом, чтобы перенаправление работало, выше в поле «domain» должны быть указаны оба варианта адреса.
Команды приложения
Есть специальные поля, где можно прописать важные команды приложения:
Команда установки (Install Command)
Команда сборки (Build Command)
Команда запуска (Start Command)
Nixpacks попытается сам определить нужные команды. Например, в случае с проектом на JavaScript/TypeScript — на основании того, какие команды есть в файле package.json.
Но в некоторых ситуациях требуется явно указать нужную команду. Например, для фреймворка Nuxt — команду запуска: node .output/server/index.mjs
HTTP-авторизация (HTTP Basic Authentication)
Пока ваш сайт не запущен в продакшн, возможно вы хотите сделать так, чтобы никто посторонний не мог открыть его. Для этого есть простое решение — HTTP-авторизация (HTTP Basic Authentication). Если её включить, то при попытке зайти на сайт сначала будет появляться браузерное окно, которое будет спрашивать у пользователя логин и пароль.
В Coolify эта опция включается в блоке «HTTP Basic Authentication». Для этого сначала нужно включить галочку «Enable». После этого появятся поля «Username» и «Password», где вы должны прописать логин и пароль, по которым можно войти на сайт.
Шаг 9. Переменные окружения (Environment Variables)
Переменные окружения это важная часть для работы большинства приложений. Это переменные, которые неуместно добавлять в код, поэтому их нужно прописывать при настройке деплоя приложения. Например, они могут содержать пароли и ключи авторизации, важные для работы приложения, или задавать настройки окружения.
То, какие именно переменные окружения нужно прописать для приложения, обычно можно прочитать в инструкции по его развертыванию (файл README.md). Также иногда в репозиториях добавляют файл-пример, вроде .env.example.
В Coolify в настройках ресурса есть специальная страница Environment Variables для настройки переменных окружения.
По умолчанию все переменные показываются в виде отдельных блоков, которые можно создавать, редактировать или удалять. Но можно нажать Developer view, чтобы переменные показывались просто в виде текстового файла — так может быть удобней.
При этом видно, что показываются два отдельных блока переменных — один блок для продакшн-приложения, а другой для превью-сборок. В рамках этой статьи мы не будем рассматривать, что такое превью-сборки и как с ними работать. Тут отметим только, что в обычной ситуации вам достаточно только редактировать переменные в первом основном блоке — «Production Environment Variables».
Важно отметить, что через переменные окружения можно задавать параметры для сборки приложения через Nixpacks. Один из часто используемых таких параметров в веб-приложениях — версия Node.js, которая задаётся через переменнуюNIXPACKS_NODE_VERSION. Сейчас Coolify сам прописывает по умолчанию значение «22», если это необходимо.
Пока что в Coolify через
NIXPACKS_NODE_VERSIONможно задать только мажорную версию Node.js — например 20, 22, 23. Дальше в статье мы разберём, почему так, и как решать связанные с этим проблемы.
Шаг 10. Деплой
Когда конфигурация ресурса настроена, мы готовы наконец выгрузить приложение. Для этого нажимаем кнопку «Deploy».
Открывается страница деплоя приложения, на которой показывается окно логов установки.
В этом окне можно отслеживать, как идёт деплой приложения. Полезные функции вынесены в верхнюю панель этого окна:
Статус деплоя — показывается сверху слева. Например,
In ProgressилиFinished.Поиск по логам.
Копирование (Copy Logs) — пригодится, чтобы скопировать все логи и отправить в ChatGPT.
Скачать логи (Download Logs).
Показать/Скрыть отметки времени (Toggle Timestamps).
Показать логи дебага (Show Debug Logs) — важная функция, которая показывает/скрывает дополнительные подробные сообщения. Она может пригодиться, чтобы точнее выявить ошибку в случае проблем. Также это удобно просто для того, чтобы отследить происходящие в данный момент процессы.
Следовать за логами (Follow Logs) — если включить, то окно будет автоматически прокручиваться по мере появления новых сообщений.
На весь экран (Fullscreen)
Деплой может занимать до нескольких минут, даже для простых сайтов. Продолжительность установки в первую очередь зависит от доступных на данный момент ресурсов на сервере (CPU и RAM).
Когда деплой будет завершен, статус в верхней панели окна логов сменится на «Finished», а в верхней части страницы появится зелёное сообщение «Running».
При этом страница с логами не закрывается сама. При желании, вы можете вернуться на страницу Configuration или перейти к проверке запущенного приложения.
Если случится ошибка, то деплой остановится, и проблемные шаги будут подсвечены красным в логе.
Отметим, что на вкладке Deployments можно увидеть список всех деплоев данного ресурса и подробную информацию по каждому. Можно увидеть, когда и как он запускался, сколько длился (Duration) и как завершился (успешно или нет). Можно кликнуть на деплой, чтобы открыть его лог.
Некоторые частые ошибки в процессе сборки
Одна из возможных ошибок — нехватка оперативной памяти. Особенно это актуально для тяжелых приложений (например, SSR-фреймворков). В таком случае в логе можно увидеть текст ошибки «exit code 137».
Или может быть, чтобы физически памяти хватает, но сборка столкнулась с лимитами, установленными в Node.js. В таком случае будет ошибка «Reached heap limit Allocation failed — JavaScript heap out of memory». Чтобы увеличить лимит, нужно в переменных окружения прописать NODE_OPTIONS=--max-old-space-size=XXXX, где вместо XXXX — нужное значение памяти. Лучше ставить его на 75% от доступной свободной памяти. Например, если на сервере 8 RAM, и из них 2 RAM уже заняты приложениями, то можно прописать NODE_OPTIONS=--max-old-space-size=4096.
Шаг 11. Проверка приложения
Чтобы проверить, что приложение работает, нужно перейти по ссылке. Для удобства, ссылки на приложение показываются при клике на пункт Links в верхнем меню.
При этом иногда, если сразу открыть страницу после первого деплоя, то будет показываться предупреждение о том, что страница не защищена — т. е. SSL-сертификат не установлен. Тогда нужно подождать пару минут, пока SSL-сертификат автоматически подключится.
Можно включить автоматическую проверку работоспособности сайта после деплоя — это называется Healthchecks.
Шаг 12. Проверка автодеплоя
Если для деплоя ресурса вы используете GitHub App, то в таком случае по умолчанию будет включен автодеплой (Auto Deploy). Это значит, что при любом изменении кода в репозитории в выбранной ветке, будет автоматически запускаться выгрузка этих изменений на сервер.
Чтобы убедиться, что автодеплой работает, для запущенного проекта нужно поменять что-то в коде. Например, это можно сделать прямо через GitHub. Можно открыть в репозитории какой-нибудь файл, нажать кнопку редактирования, внести какое-нибудь незначительное изменение, затем нажать «Commit changes» и подтвердить изменения в модальном окне. Сразу же запустится автоматическая выгрузка — в настройках данного ресурса в списке «Deployments» появится новый деплой в статусе «In progress».
При желании, автодеплой можно выключить в Configurations на странице Advanced. Для этого в самом верху нужно убрать галочку «Auto Deploy».
❯ Проблема с версиями Node.js для Nixpacks
Nixpacks это важная часть внутри Coolify — за счет этого инструмента обеспечивается быстрый деплой приложений, без необходимости самостоятельной подготовки Dockerfile.
Однако с Nixpacks есть серьезная проблема — этот проект теперь заморожен и больше не поддерживается. Его разработчики переключились на аналогичный проект Railpack. В перспективе Coolify перейдет на Railpack или на собственный аналог, но неизвестно, когда это случится.
Сборку через Nixpacks по прежнему можно использовать в Coolify, но появились неудобства. Одно из них связано с Node.js — самой популярной средой выполнения JS-приложений на бэкенде.
В Coolify версия Node.js для ресурса указывается в переменной окружения NIXPACKS_NODE_VERSION. Однако, там можно указать только мажорную версию (20, 22 и т. д.), а точная версия будет выбрана автоматически. Например, для Node.js 22 будет использоваться минорная версия v22.6.
Но это уже устаревшая версия, на которой современные проекты не пойдут. Например, Vite на данный момент требует как минимум v20.19 или v22.12. А если указать в NIXPACKS_NODE_VERSION более новую мажорную версию, например 24 или 25, то приложение вообще не запустится.
В официальной документации Coolify есть специальная страница по этой проблеме. И там предлагается обходное решение. Нужно добавить в репозиторий в корневой папке проекта файл с настройками nixpacks.toml. И в этом файле через параметр nixpkgsArchive указать нужный хэш коммита проекта Nixpkgs на GitHub.
Nixpkgs — это популярный репозиторий пакетов и модулей. А хэш коммита — это уникальный идентификатор коммита любого проекта на GitHub. Хэш можно увидеть в ссылке на коммит. Например, если ссылка
https://github.com/NixOS/nixpkgs/commit/51ad838b03a05b1de6f9f2a0fffecee64a9788ee, то хэшем будет51ad838b03a05b1de6f9f2a0fffecee64a9788ee.
Вот что именно документация Coolify предлагает прописать в nixpacks.toml:
[phases.setup] nixpkgsArchive = '51ad838b03a05b1de6f9f2a0fffecee64a9788ee'
И тогда при деплое приложения для Node.js 22 точная версия будет уже v22.13.1. Это всё еще не самая свежая версия, но хотя бы соответствует минимальным требованиям для Vite.
А чтобы получить ещё более актуальный хэш, можно открыть все коммиты последней стабильной версии Nixpkgs, скопировать ссылку на последний коммит и взять из неё хэш. Например, на момент написания статьи это был коммит с хэшем fa83fd837f3098e3e678e6cf017b2b36102c7211.
Получим следующий nixpacks.toml:
[phases.setup] nixpkgsArchive = 'fa83fd837f3098e3e678e6cf017b2b36102c7211'
Это уже даст версию v22.21.1. На момент написания статьи это одна из последних минорных версий внутри мажорной версии 22, что очень хорошо. А если с этим хэшем прописать в переменных окружения NIXPACKS_NODE_VERSION=24, то полная версия будет v24.13.0 — самая свежая из 24 на момент публикации.
Просуммируем ситуацию:
Если вы хотите поставить через Nixpacks приложение, которому нужен актуальный Node.js, то вам обязательно нужно добавлять в корень папки проекта файл
nixpacks.toml, где должен быть прописан хэш нужного коммита Nixpkgs.Это делает невозможным деплой подобных проектов напрямую из чужих открытых репозиториев, если они не были заранее подготовлены. Т. е. вам придется создавать собственную копию репозитория, чтобы можно было добавить внутри
nixpacks.toml.Вы можете взять нужное значение хэша из документации Coolify, но тогда версия Node.js будет на грани устаревания. Для актуальных версий Node.js вам нужен хэш актуальных коммитов Nixpkgs.
Значение хэша актуального коммита вам нужно получать самостоятельно. Надёжней всего будет посмотреть на GitHub. Или для начала можно взять предложенное нами выше: 'fa83fd837f3098e3e678e6cf017b2b36102c7211'.
А если вам вдруг нужна конкретная точная версия Node.js, то нужно найти конкретный коммит, который ей соответствует.
Но с этими самостоятельно найденными значениями хэша никто не гарантирует стабильную работу Nixpacks. Хотя пока вроде бы жалоб нет.
Единственная альтернатива описанному выше сценарию работы — вместо сборки через Nixpacks использовать сборку через Dockerfile.
Ждём, когда Coolify перейдёт с Nixpack на альтернативное решение, где такой проблемы уже не будет.
❯ Примеры
А теперь переходим к конкретным примерам деплоя приложений с помощью Coolify.
Мы подготовили специальный репозиторий с несколькими простейшими примерами — это всё стартовые проекты, которые предлагаются фреймворками. Все проекты из репозитория написаны на JavaScript/TypeScript, потому что это самые популярные языки программирования в веб-разработке. Но конечно, Coolify не ограничивается только JS/TS, а позволяет запускать и проекты на других языках.
Также, для самостоятельного тестирования Coolify вы можете посмотреть на демо-проекты из официального репозитория coolify-examples. Но мы на них не будем останавливаться.
В конце каждого примера будем озвучивать, сколько примерно оперативной памяти занимал процесс сборки образа и сколько оперативной памяти занимает сам уже запущенный контейнер с приложением. Это позволит вам примерно сориентироваться, сколько RAM требуется на вашем сервере для работы с подобным приложениями. Но конечно, надо иметь в виду, что эти цифры — лишь минимум, для самого базового варианта сайта. В полноценных сложных проектах с реальными пользователями требования к железу будут больше.
Выбор типа источника
Мы не будем указывать для примеров конкретный тип источника (Public Repository, Private Repository with GitHub App или Private Repository with Deploy Key) — выбирайте наиболее удобный для вас вариант. Это почти не влияет на то, как будет создаваться и настраиваться ресурс. Небольшие отличия лишь на шаге выбора репозитория.
Если вы хотите повторять за примерами ниже и ставить приложения из нашего открытого демо-репозитория, то вариант через «Public Repository» будет самым простым.
Универсальные настройки
Некоторые настройки ресурсов в наших примерах будут идентичные для всех проектов. Поэтому, чтобы не повторяться, перечислим их сразу заранее:
Domains:
https://XXXXX.ivanivanov.ru,https://www.XXXXX.ivanivanov.ru, где вместо XXXXX — нужный вам поддомен, а вместо ivanivanov.ru — ваш домен. Для удобства можно прописывать в качестве поддомена имя ресурса.Direction: Redirect to non-www.
Environment Variables: Там, где ничего не указано насчет переменных окружения, оставляем вариант по умолчанию (NIXPACKS_NODE_VERSION=22)
Ports Exposes: Не трогаем. Нужное значение («3000» или «80») будет подставляться автоматически.
Branch: Не меняем. В наших примерах будет «main».
Пример 1 — Статичный сайт (Static)
Ссылка: https://github.com/nickneustroev/coolify-demo-examples/tree/main/static
Стэк технологий:
В данном случае у нас уже готовые файлы сайта: HTML и CSS. С ними ничего не нужно делать, достаточно просто отдавать их по запросу.
Форма создания ресурса:
Build Pack: Static
Base Directory: /static
Настройки ресурса:
Name: coolify-static
Результат:
Минимальные требования:
Использовалось RAM во время сборки: < 100 mb
Занимает оперативной памяти: 3 mb.
Пример 2 — Vue
Ссылка: https://github.com/nickneustroev/coolify-demo-examples/tree/main/vue-starter
Стэк технологий:
Vue — это JavaScript-фреймворк для создания фронтенд-приложений (SPA).
Форма создания ресурса:
Build Pack: Nixpacks
Base Directory: /vue-starter
Is it a static site: да
Publish Directory: /dist
Настройки ресурса:
Name: vue-starter
Is it a SPA: да
Результат:
Минимальные требования:
Использовалось RAM во время сборки: 700 mb
Занимает оперативной памяти: 5 mb.
Пример 3 — React с Next (в режиме SSR)
Ссылка: https://github.com/nickneustroev/coolify-demo-examples/tree/main/next-starter
Стэк технологий:
React — JavaScript-фреймворк/библиотека для создания фронтенд-приложений (SPA).
Next — это фронтенд-фреймворк на основе React для создания приложений с серверным рендерингом (SSR).
Форма создания ресурса:
Build Pack: Nixpacks
Base Directory: /next-starter
Is it a static site: нет
Настройки ресурса:
Name: next-starter
Результат:
Минимальные требования:
Использовалось RAM во время сборки: 700 mb
Занимает оперативной памяти: 108 mb.
Пример 4 — React с Tanstack Start (в режиме SSR)
Ссылка: https://github.com/nickneustroev/coolify-demo-examples/tree/main/tanstack-start-shadcn
Стэк технологий:
React — JavaScript-фреймворк/библиотека для создания фронтенд-приложений (SPA).
Tanstack Start — это новый фронтенд-фреймворк для создания приложений с серверным рендерингом (SSR), который используется поверх другого фреймворка (в данном случае — React).
shadcn/ui — это популярная UI-библиотека.
Форма создания ресурса:
Build Pack: Nixpacks
Base Directory: /next-starter
Is it a static site: нет
Настройки ресурса:
Name: next-starter
Start command:
node .output/server/index.mjs
Результат:
Минимальные требования:
Использовалось RAM во время сборки: 1200 mb
Занимает оперативной памяти: 31 mb.
Пример 5 — Nuxt (в режиме SSR)
Ссылка: https://github.com/nickneustroev/coolify-demo-examples/tree/main/nuxt-ui-starter
Стэк технологий:
Vue — это JavaScript-фреймворк для создания фронтенд-приложений (SPA).
Nuxt — это фронтенд-фреймворк на основе Vue для создания приложений с серверным рендерингом (SSR).
Nuxt UI — это UI-библиотека для Vue/Nuxt. Наш обзор на неё.
Форма создания ресурса:
Build Pack: Nixpacks
Base Directory: /nuxt-starter
Is it a static site: нет
Настройки ресурса:
Name: next-starter
Start command:
node .output/server/index.mjs
Результат:
Минимальные требования:
Использовало��ь RAM во время сборки: 2400 mb
Занимает оперативной памяти: 54 mb.
Пример 6 — NestJS
Ссылка: https://github.com/nickneustroev/coolify-demo-examples/tree/main/nest-starter
Стэк технологий:
NestJS — это серверный фреймворк на базе Node.js для создания backend-приложений.
Форма создания ресурса:
Build Pack: Nixpacks
Base Directory: /nest-starter
Is it a static site: нет
Настройки ресурса:
Name: nest-starter
Результат:
При открытии главной страницы будет показываться сообщение «Hello, world!».
Минимальные требования:
Использовалось RAM во время сборки: 700 mb
Занимает оперативной памяти: 130 mb.
Пример 7 — Telegram-бот на Grammy
Ссылка: https://github.com/nickneustroev/coolify-demo-examples/tree/main/grammy-demo-bot
Стэк технологий:
Grammy — это библиотека для создания Telegram-ботов на Node.js и TypeScript.
Создание бота:
Откройте Telegram и найдите @BotFather.
Отправьте команду
/newbot.Следуйте инструкциям для создания бота.
Скопируйте полученный токен.
Форма создания ресурса:
Build Pack: Nixpacks
Base Directory: /grammy-demo-bot
Настройки ресурса:
Name: grammy-demo-bot
Domains: grammy-demo-bot (домен для бота не нужен, но если не заполнить, то Coolify выдаст ошибку)
Direction: оставляем как есть
Environment Variables: добавляем переменную BOT_TOKEN со значением вашего токена, полученного от BotFather, например
BOT_TOKEN=1234569854:AAFm6s4_sIsdjsdf7239sdf9sdfW7rdsBg
Результат:
Минимальные требования:
Использовалось RAM во время сборки: < 100 mb
Занимает оперативной памяти: 39 mb.
Пример 8 — Nuxt через Dockerfile
Примеры выше показывали установку через Nixpacks. Для сравнения, давайте сделаем одну установку и через Dockerfile. Повторно возьмём проект nuxt-ui-starter.
Ссылка: https://github.com/nickneustroev/coolify-demo-examples/tree/main/nuxt-ui-starter
Форма создания ресурса:
Build Pack: Dockerfile
Base Directory: /nuxt-starter
Отметим, что когда вы выбираете «Build Pack: Dockerfile», то все остальные поля скрываются, кроме Base Directory.
Настройки ресурса:
Name: next-starter
В настройках ресурса тоже исчезли некоторые поля. Например, больше не нужно прописывать «Start command» — теперь нужные команды описаны в Dockerfile.
Результат:
Получаем такой же сайт, когда до этого в примере с Nuxt.
Минимальные требования:
Использовалось RAM во время сборки: 2200 mb
Занимает оперативной памяти: 47 mb.
❯ Заключение
Мы убедились, что Coolify позволяет легко и удобно запускать на собственном сервере различные приложения: как веб-сайты, так и бэкенд-приложения, Telegram-боты и остальные программы.
И хотя разнообразие способов деплоя и число разных настроек велико и может запутать новичков, но мы постарались объяснить самое важное, чтобы вы могли без проблем начать работать с Coolify.
Чтобы не пропустить следующую статью: https://t.me/nickneustroev_blog
Новости, обзоры продуктов и конкурсы от команды Timeweb.Cloud — в нашем Telegram-канале ↩
Перед оплатой в разделе «Бонусы и промокоды» в панели управления активируйте промокод и получите кэшбэк на баланс.
