gem Capistrano

Ruby 🇺🇦

В цій інструкції я поділюся своїми кроками по імплементації gem-у capistrano на проект RubyCoin, а також постараюся описати більшість налаштувань у файлах та для чого вони взагалі призначені. Опис налаштувань з файлів буде після самої інструкції по імплементації.

Отже, нагадую, що на проекті RubyCoin я використовую такі технології як:

Rails 7
Postgresql
Cssbundling-rails
Jsbundling-rails
Hotwire
Propshaft

На сервері, відповідно, буду використовувати:

Puma
Nginx
RVM

P.S. В capistrano з propshaft-ом є деякі нюанси, тому в config\deploy.rb я добавлю рядок для налаштування :assets_manifests. Хто використовує sprockets – цього робити не потрібно.

P.S.S. деплой відбувається через Linux, або ж Windows (не через WSL).

Про gem Capistrano

Gem "capistrano-rails" є розширенням для Capistrano - це засіб для автоматизації розгортання додатків на віддаленому сервері (далі деплой). "capistrano-rails" надає додаткові задачі для розгортання Rails-додатків, такі як підключення до бази даних, примірників та конфігураційних файлів, компіляція ассетів та інші рутинні завдання. З його допомогою можна легко та швидко розгортати Rails-додатки на віддалених серверах без необхідності вручну виконувати рутинні операції.

Імплементація capistrano та його додатків

1) Для початку нам потрібно добавити всі додаткові геми для деплою в Gemfile.

2) Далі встановлюємо ці gem-и, виконавши команду:

3) Далі ініціалізуємо Capistrano в проекті:

4) Це створить декілька файлів та директорій для налаштування та використання Capistrano:

Capfile
config\deploy.rb
config\deploy\production.rb
config\deploy\staging.rb

5) У файлі Capfile пишемо наступні налаштування:

6) У файлі config\deploy.rb пишемо наступне:

7) Створюємо та налаштовуємо файл lib/capistrano/tasks/setup.rake:

8) Добавляємо цей код в config/environments/production.rb:

9) Добавляємо шлях до cable в config/routes.rb:

10) Налаштування для config/cable.yml

Цей файл містить налаштування для Action Cable, вбудованої бібліотеки Ruby on Rails для роботи з WebSockets.

У розробці та тестуванні для Action Cable використовується Redis з локальним URL (redis://localhost:6379/1). Для середовища продакшен використовується змінна середовища REDIS_URL. Якщо змінна середовища не встановлена, Redis використовуватиме локальний URL (redis://localhost:6379/1).

Цей файл є важливим для правильної конфігурації Action Cable в різних середовищах. Він вказує, який адаптер має використовуватися та який URL Redis має використовуватися для Action Cable у кожному середовищі.

11) Перевіряємо налаштування до бази даних config/database.yml

Цей файл містить конфігурацію бази даних для різних оточень: розробки, тестування та продукції.

Ключовими параметрами є:

adapter: вказує тип бази даних, у даному випадку Postgresql.
host, port: адреса та порт для підключення до бази даних, взяті з змінних середовища.
username, password: логін та пароль користувача бази даних, також взяті з змінних середовища.
encoding: кодування бази даних.
database: назва бази даних, для кожного з оточень зазначено свою.

Для продакшен зазначено додаткові логін та пароль для користувача бази даних.

12) Запускаємо команду для виконання деплою в терміналі:

На цьому моменті на вашому сервері вже має бути все встановлене та налаштоване, щоб деплой пройшов успішно.

Мою інструкцію як встановити та налаштувати все необхідне на віддаленому сервері для розгортання проекту на ньому можна подивитися тут.

Теорія та пояснення коду

1.1 Перший крок. Добавлення потрібних гемів у .Gemfile

gem 'capistrano' є інструментом для автоматизованої розгортки додатків на віддалених серверах. Він дозволяє з локальної машини керувати процесом розгортки на віддаленому сервері, роблячи його швидшим і менш помилковим. Capistrano забезпечує зручний механізм розгортки, автоматично виконує задачі, такі як клонування репозиторію, міграції бази даних і рестарт сервера після розгортки. Використання Capistrano дозволяє зосередитися на розробці додатку, а не на процесі його розгортки.
gem 'capistrano3-puma' - це розширення для Capistrano, яке дозволяє легко розгортати Rails додатки, що використовують сервер додатків Puma. Puma - це високопродуктивний сервер додатків для Ruby, який дозволяє обробляти багато запитів одночасно, що робить його ідеальним вибором для розгортання Rails додатків. А також gem 'capistrano3-puma' надає ряд задач для Capistrano, які дозволяють легко керувати Puma сервером під час розгортання та деплою. Він дозволяє автоматично зупиняти та запускати сервер Puma під час деплою, а також налаштовувати параметри запуску сервера. Крім того, він також дозволяє налаштовувати кількість робочих процесів Puma для оптимальної продуктивності.
capistrano-bundler - це gem, який допомагає автоматизувати процес установки та налаштування Ruby-залежностей вашого додатку на віддаленому сервері під час розгортання (deploy) з допомогою Capistrano. Цей gem виконує команди bundle install на віддаленому сервері та кешує залежності для покращення часу розгортання у майбутньому. Використання capistrano-bundler допомагає уникнути проблем з версіями залежностей та забезпечує однаковість середовищ між розгортаннями.
gem capistrano-rails - це розширення для фреймворку Capistrano, яке надає додаткові функції для деплою веб-додатків на Ruby on Rails. Зокрема, він додає підтримку деплою конфігурації бази даних та предзапуску Rails-консолі під час деплою. Також він автоматично виконує переддеплойні та постдеплойні задачі, необхідні для роботи з Rails-додатками
gem 'capistrano-rvm' є розширенням для Capistrano, яке дозволяє встановлювати та використовувати RVM (Ruby Version Manager) на сервері. RVM дозволяє зберігати кілька версій Ruby та дозволяє швидко перемикатися між ними. При використанні 'capistrano-rvm', Capistrano буде встановлювати ту версію Ruby, яку ви вказали в конфігурації, та налаштовувати середовище, щоб воно використовувало цю версію під час виконання команд на сервері. Також, воно дозволяє встановлювати та використовувати gemset'и RVM на сервері. Таким чином, 'capistrano-rvm' допомагає забезпечити однакове середовище виконання на кожному сервері, на якому виконується ваш додаток, і знижує ризик помилок, пов'язаних з різними версіями Ruby та gemset'ів.
gem capistrano-yarn дозволяє виконувати команди управління залежностями yarn при деплої за допомогою Capistrano. Цей гем автоматизує процес встановлення та оновлення залежностей yarn, необхідних для правильної роботи JavaScript-коду на сервері, та забезпечує їх сумісність з версією Node.js, яка встановлена на сервері. Зокрема, він додає задачі Capistrano для виконання команд yarn install та yarn upgrade. Використання capistrano-yarn дозволяє забезпечити стабільність та надійність деплою додатку, який містить JavaScript-код.

4.1. Четвертий крок. Налаштування з Capfile

Цей код вказує Capistrano використовувати плагін Capistrano::SCM::Git, який дозволяє використовувати Git як засіб контролю версій для деплою проекту. Цей плагін містить необхідні таски для виконання операцій з Git під час деплою, таких як клонування репозиторію, витягування коду з відповідної гілки, комітів тощо. Встановлення плагіну дозволяє з легкістю налаштувати деплой проекту з використанням Git як засобу контролю версій.

Код "require 'capistrano/rvm'" в Capfile використовується для підтримки Ruby Version Manager (RVM) в Capistrano, який дозволяє використовувати різні версії Ruby та gemsets на сервері.

Цей код підключає Capistrano плагін capistrano-bundler, який автоматично встановлює необхідні геми з файлу Gemfile для кожного релізу під час розгортання додатку на сервері. Це дозволяє забезпечити консистентність версій гемів між різними релізами додатку.

Це використовують для попередньої компіляції (precompilation) і підготовки (preparation) ассетів, таких як CSS та JS, перед тим, як вони будуть задіяні на продакшен сервері. Вона дозволяє підготувати та зменшити розмір ассетів для продакшен середовища, що дозволяє поліпшити час завантаження сторінок та зменшити обсяг передачі даних.

Цей код підключає плагін Capistrano для керування міграціями бази даних Ruby on Rails. Коли ви розгортаєте додаток Rails на віддаленому сервері з допомогою Capistrano, ви хочете мати можливість виконувати міграції бази даних на віддаленому сервері так само легко, як і на локальній машині. Цей плагін додає задачі Capistrano, які дозволяють вам виконувати міграції бази даних на віддаленому сервері за допомогою команди cap production deploy:migrate.

Цей код використовується для налаштування Capistrano для деплою Ruby on Rails додатку, який використовує Puma як веб-сервер. Він підключає плагін Capistrano::Puma та його розширення Capistrano::Puma::Systemd, щоб автоматизувати деплой та управління веб-сервером Puma під час релізів. Плагін Capistrano::Puma також надає засоби для контролю над станом Puma, включаючи перезапуск, зупинку та старт сервера.

5.1. П’ятий крок. Налаштування з config\deploy.rb

Цей код вказує Capistrano, на який сервер потрібно розгорнути додаток. Конкретно в даному випадку вказується IP-адреса сервера (45.90.59.143), порт (22) і ролі (web, app, db), які сервер буде виконувати. Роль 'web' означає, що сервер буде використовуватись для доступу до веб-додатку, роль 'app' - що це є сервером додатку, а роль 'db' - що це є сервером бази даних. Крім того, параметр 'primary' вказує на те, що цей сервер буде використовуватись як основний сервер, до якого будуть виконуватись підключення під час розгортання додатку.

Цей рядок визначає назву додатку, який буде деплоїтись на сервер. В даному випадку додаток називається "ronico". Дана змінна буде використовуватись в інших конфігураційних файлах для Capistrano, наприклад, для шляху до папки з додатком.

Цей рядок налаштовує Git-репозиторій, з якого будуть забиратися файли для релізів, тобто для деплою на сервер. :repo_url - це URL або SSH-шлях до репозиторію, з якого будуть братися файли. У цьому випадку git@github.com:ronico-ua/ronico.git є SSH-шлях до репозиторію на Github.

Цей код встановлює гілку (branch) з якої буде здійснюватись деплой проекту на сервер. Зазвичай гілкою за замовчуванням є master, що означає головну гілку репозиторію з кодом. Однак, якщо потрібно здійснити деплой з іншої гілки, то це можна встановити за допомогою цього коду. Наприклад, якщо потрібно здійснити деплой з гілки develop, то код буде виглядати наступним чином: set :branch, 'develop'.

Цей код вказує користувача, який буде використовуватись для підключення до серверу за допомогою SSH. У даному випадку, вказано, що для підключення до серверу буде використовуватись користувач "root".

Цей код задає шлях на сервері, до якого будуть розгортатися файли проекту. В даному випадку, шлях складається зі строки "/home/", поточного користувача (який був встановлений в попередньому рядку), директорії "apps" та назви додатку, яка була встановлена в першому рядку. Загальний вигляд шляху на сервері, до якого будуть розгортатися файли, має вигляд "/home/користувач/apps/назва_додатку".

Цей код встановлює параметри SSH, які будуть використовуватися для з'єднання з сервером під час деплою.

Перший параметр, forward_agent: true, вказує на те, що на локальному комп'ютері має бути запущений ssh-agent і що під час з'єднання з сервером потрібно перенаправляти ключі з цього ssh-agent.

Другий параметр, user: fetch(:user), вказує на ім'я користувача, під яким ми будемо з'єднуватися з сервером. Значення цього параметру береться зі змінної :user.

Третій параметр, keys: %w[~/.ssh/id_rsa.pub], вказує на список ключів, які будуть використовуватися для з'єднання з сервером. У даному випадку використовується публічний ключ ~/.ssh/id_rsa.pub.

Цей код встановлює значення змінної :stage на :production. Змінна :stage використовується для вказівки середовища, в якому ми розгортаємо додаток. Наприклад, ми можемо мати різні середовища, такі як :staging (для тестування на віддаленому сервері перед розгортанням на виробництві), :production (для виробничого середовища) та інші. Залежно від значення :stage, Capistrano буде виконувати різні налаштування та команди розгортання. Наприклад, для розгортання додатку на сервері для середовища :production, ми можемо запустити команду cap production deploy.

Цей код говорить Capistrano про те, що при виконанні команд на віддаленому сервері має використовуватися "pseudo terminal". Pseudo terminal - це спеціальна форма терміналу, яка дозволяє інтерактивно взаємодіяти з програмами, що запускаються на віддаленому сервері.

Це корисно, наприклад, для запуску інтерактивних скриптів або команд, що очікують введення користувачем. Налаштування цієї опції може допомогти уникнути проблем з введенням користувачем пароля або інших даних під час виконання деплою.

Цей код вказує Capistrano не використовувати команду sudo під час деплою. Замість цього будуть виконуватися команди з використанням привілеїв користувача, під яким відбувається деплой, що може бути вказано змінною :user в цьому ж файлі. Це забезпечує безпечний та зручний спосіб для деплою додатків, оскільки команди виконуються з правами поточного користувача, і не потрібно вводити пароль sudo під час деплою.

Цей код встановлює спосіб деплою проекту на віддалений сервер. Значення :remote_cache вказує на те, що при деплої буде використано віддалене кешування, тобто буде завантажена лише остання версія коду, а не весь репозиторій, що прискорює процес деплою та заощаджує місце на сервері.

Цей код встановлює шлях для сокета Puma сервера, який буде використовуватися для з'єднання з Rails додатком після релізу.

Конфігураційний параметр puma_bind вказує адресу сокету Puma на сервері, де буде розташовуватися UNIX-сокет за замовчуванням. Створюється в директорії shared_path/tmp/sockets, де shared_path - шлях до директорії, яка буде спільно використовуватися між різними версіями додатку. Отже, код встановлює адресу UNIX-сокету для Puma сервера, що дозволяє зменшити навантаження на сервер при обробці запитів.

Цей код встановлює шлях до файлу зі станом сервера Puma. Puma - це сервер додатків, що виконується на Ruby, і використовується зазвичай з додатками Ruby on Rails. За допомогою цього параметру вказується шлях до файлу, де буде зберігатися стан сервера Puma, тобто інформація про його поточний стан, щоб можна було зупинити або перезапустити сервер. Файл із станом додатку зазвичай зберігається в спільній області збереження між різними релізами додатку.

Цей код встановлює шлях до PID-файлу для Puma сервера. Визначення PID (індентифікатор процесу) - це унікальний ідентифікатор, який присвоюється процесу операційною системою. PID-файл зберігає цей ідентифікатор, і Capistrano може використовувати цей файл, щоб контролювати стан процесу Puma. Задання цього шляху дозволяє Capistrano знайти і зупинити/запустити процес Puma на віддаленому сервері.

Ці два рядки коду використовуються для налаштування логування Puma, що є сервером додатків Ruby. В першому рядку set :puma_access_log, "#{release_path}/log/puma.error.log" вказується шлях до файлу журналу доступу Puma. У другому рядку set :puma_error_log, "#{release_path}/log/puma.access.log" вказується шлях до файлу журналу помилок Puma. Обидва файли журналів будуть створені в каталозі log директорії відповідного релізу, який буде створений під час розгортання додатку.

Цей код вказує, що перед запуском сервера Puma варто завантажити додаток заздалегідь. Це дозволяє зменшити час запуску додатку та збільшити продуктивність.

Цей рядок встановлює час очікування для роботи працівників сервера у більшості проксі-серверів, таких як Nginx. Якщо з'єднання з сервером не здійснюється протягом часу, заданого цим параметром, проксі-сервер перестає відправляти запити до Puma, тим самим позбавляючи Puma від надмірного трафіку. За замовчуванням цей параметр встановлюється в nil, що означає, що Puma буде працювати без обмежень часу для працівників.

Цей код говорить Puma про те, що треба ініціалізувати ActiveRecord з базою даних при запуску Puma. ActiveRecord це ORM (Object-Relational Mapping) для Ruby, яке дозволяє працювати з базами даних, як з об'єктами, що дозволяє писати менше коду SQL і більше коду Ruby. Якщо :puma_init_active_record установлено в true, Puma забезпечує з'єднання з базою даних при запуску сервера.

Цей код вказує на те, що потрібно включити Puma socket service при запуску сервера. Це означає, що Puma буде слухати підключення до сокету замість прямого з'єднання з сервером за допомогою порту. Включення цієї опції дозволяє зменшити навантаження на сервер і покращити його продуктивність.

Цей код - це workaround, тобто спосіб обійти проблему, яка виникла в процесі розгортання застосунку з використанням gem-у Propshaft замість Sprockets.

Цей workaround використовує lambda-функцію для створення шляху до маніфест-файлу assets для кожної версії, використовуючи відносний шлях до папки public та префіксу, що вказується у налаштуваннях assets.

Цей код розв'язує проблему і дозволяє Capistrano успішно розгортати нові версії додатку з оновленими assets.

Цей код використовується для додавання файлів, які повинні бути посиланнями між релізами. Зокрема, цей код додає список файлів у масив :linked_files, який буде використовуватися під час деплою.

В даному випадку, масив містить два файлу: config/master.key і config/database.yml. Ці файли повинні бути створені на сервері, на який деплоїться проект, та будуть використовуватися між різними релізами проекту. За допомогою цього коду, файли будуть створені у папці shared на сервері і будуть посилатися на них з релізів, що створюються під час деплою. Це дозволить зберігати конфіденційну інформацію, таку як ключі шифрування або дані підключення до бази даних, поза репозиторієм проекту і захищати їх від несанкціонованого доступу.

Цей код використовується у Capistrano для налаштування директорій, які будуть зв'язані між релізами.

linked_dirs це масив директорій, які будуть симлінками зв'язані між попереднім та новим релізами. Це робиться для того, щоб зберегти стан даних в цих директоріях між поновленнями програми. Наприклад, логи, кеш, файли, що завантажуються користувачами тощо.

У даному коді, ми вказали директорії log, tmp/pids, tmp/cache, tmp/sockets, vendor/bundle, public/assets, і public/uploads. Ці директорії будуть зв'язані між релізами і зберігатимуть стан даних між поновленнями програми.

7.1. Сьомий крок. Налаштування середовища production.rb

Цей код містить налаштування для середовища продакшену в Ruby on Rails додатку.

config.action_cable.allowed_request_origins = ["http://45.90.59.143"] встановлює допустимі походження запитів для Action Cable. Action Cable - це бібліотека для розробки функцій веб-сокетів в Ruby on Rails додатку. Ця опція вказує, що дозволені тільки запити з домену http://45.90.59.143. Це важливо для забезпечення безпеки вашого додатку.

config.assets.compile = false встановлює, що веб-сервер не буде компілювати ассети (зображення, таблиці стилів, скрипти тощо) для продакшену. Замість цього, веб-сервер буде використовувати скомпільовані ассети з папки public/assets. Це дозволяє зменшити навантаження на сервер і зробити статичні ресурси доступними для кешування в браузерах клієнтів.

8.1. Восьмий крок. Монтування Action Cable сервера на шлях

Код з восьмого кроку відповідає за монтування Action Cable сервера на шлях /cable. Action Cable - це частина фреймворку Ruby on Rails, яка дозволяє створювати реальний час (real-time) веб-застосунки.

Action Cable побудовано на основі протоколу WebSocket, і він може працювати разом з іншими бібліотеками, наприклад, React чи Angular.

За допомогою mount ActionCable.server, at: '/cable' Action Cable сервер розташовується на заданому шляху /cable, що дозволяє створити з'єднання між клієнтом та сервером за допомогою WebSocket.

Таким чином, клієнт зможе підключитися до Action Cable server і використовувати його функціональність для отримання або надсилання даних в режимі реального часу.

Заключення

У статті було детально розглянуто налаштування та використання gem Capistrano для розгортання проекту на сервері. Capistrano дозволяє з легкістю виконувати складні розгортання, зберігаючи резервні копії попередніх версій, збірку коду, змінні середовища та багато іншого.

Налаштування сервера не було розглянуто в цій інструкції, але в цілому стаття надає чітке розуміння того, як за допомогою Capistrano можна автоматизувати процес розгортання проектів на віддаленому сервері.

Лінк, для того, щоб переглянути кінцевий код (могли бути деякі дрібні зміни) з цієї інструкції, доступний для тих людей, які були добавлені в співучасники проекту.

Нагадую, якщо ви зацікавлені спостерігати безпосередньо за роботою з проектом чи навіть стати співучасником, пишіть мені в приватні повідомлення, але одразу вказуйте свій email/логін з github-y та ціль (спостерігач/співучасник).

Чат для спілкування - лінк.
Канал - лінк.