Capistrano Deployment

This guide explains how to deploy Hyvä themes with Capistrano, focusing on generating Tailwind CSS during deployment. It covers creating a custom Rake task, configuring theme paths, and ensuring Node.js is available. `capistrano-magento2` is a Ruby-based deployment tool for Magento projects that provides hooks into the deployment lifecycle.

Prerequisites

capistrano-magento2 configured for your project
Node.js and npm installed on deployment servers (see Server Requirements)
Your Hyvä theme's web/tailwind directory must contain package.json and Tailwind configuration

Tailwind Stylesheet Generation

If your production Tailwind CSS stylesheet is not committed to version control, Capistrano must build it during deployment. This build process runs before the static content deployment phase.

Step 1: Create the Tailwind Rake Task

Create `tailwind.rake` in your project's `lib/capistrano/tasks` directory. This Rake task will iterate through configured theme paths, install npm dependencies, and run the Tailwind build command:

namespace :deploy do
    desc 'Build tailwindCSS'
    task :hyva_tailwind_build do
      on roles(:all) do
        fetch(:hyva_tailwind_paths, []).each do |tailwind_path|
          within release_path + tailwind_path do
            execute :npm, :ci
            execute :npm, :run, "build"
          end
        end
      end
    end
  end

Step 2: Configure Theme Paths

In `config/deploy.rb`, define `hyva_tailwind_paths` with your Hyvä theme's Tailwind directory paths. Replace `Vendor/ThemeName` with your actual theme vendor and name:

set :hyva_tailwind_paths, [
  'app/design/frontend/Vendor/ThemeName/web/tailwind'
]

For multiple themes, add each Tailwind path to the array:

set :hyva_tailwind_paths, [
  'app/design/frontend/Vendor/ThemeOne/web/tailwind',
  'app/design/frontend/Vendor/ThemeTwo/web/tailwind'
]

Step 3: Register the Task in the Deployment Lifecycle

In `config/deploy.rb`, register the Tailwind build task to run before Magento's static content deployment. This ensures stylesheets are ready for `pub/static`:

before 'magento:setup:static-content:deploy', 'deploy:hyva_tailwind_build'

Server Requirements

Deployment servers require Node.js and npm for the Tailwind build process. The Rake task uses `npm ci` for dependencies and `npm run build` for stylesheet generation.

Optional: Managing Node.js Versions with NVM

If your deployment servers use NVM (Node Version Manager), integrate Capistrano with the capistrano-nvm gem to specify Node.js versions for deployment.

Step 1: Add the NVM Gem

Add `capistrano-nvm` to your `Gemfile`:

gem 'capistrano-nvm', :git => 'https://github.com/koenpunt/capistrano-nvm.git', require: false

Step 2: Require the Module

Require the NVM module in your `Capfile`:

require 'capistrano/nvm'

Step 3: Configure NVM Settings

Configure NVM in `config/deploy.rb`. Set `nvm_type` to `:user` for per-user installations or `:system` for system-wide:

set :nvm_type, :user
set :nvm_node, 'v20.19.5'

On this page

Navigation