capistrano-nextjs 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 06e138f48096ae45c17c5bb40ec3b3331128dc4c1d2b7b69bed5a52d8fdb7332
+  data.tar.gz: 3e03654dac9515fc45d142ddcd94557e4a162d508801c9cd5a78422c37b678b5
+SHA512:
+  metadata.gz: f65195942ae440a5a079564e11218d646318ab7eeb8eb2d1388fdca972be96b12f0fe615e004b3301b062cde31c821048036d76e4a985ad3d414be51ca57da6d
+  data.tar.gz: 011cd3efcec06a345b1e9f570b0c625550a896549c0026528381944f7e5e1cee38a576cb2bb2d47782951720a68705241c2ac6d7131f09a545ced547a1c394f3

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-07-07
+
+### Added
+
+- Initial release of capistrano-nextjs
+- Next.js application deployment support with Capistrano
+- Systemd service integration for Next.js applications
+- Support for pnpm package manager
+- Automatic build and deployment hooks with proper sequencing
+- Graceful shutdown support
+- Environment variable management
+- Service management tasks (start, stop, restart, status)
+- Installation and uninstallation of systemd services
+- Database migration support before build process
+- RuboCop integration for code quality and style enforcement
+
+### Features
+
+- Automatic detection of pnpm executable
+- NODE_ENV environment variable management
+- Customizable service templates
+- User and system service support
+- Logging configuration
+- Background process management
+- Optimized deployment flow: migrate → build → deploy
+- Code linting and formatting with RuboCop
+
+### Changed
+
+- Reordered deployment hooks to run migrations before build process
+- Improved deployment sequence for better reliability
+- Added RuboCop configuration and fixed all linting issues
+- Moved development dependencies from gemspec to Gemfile
+- Added MFA requirement for gem publishing

data/LICENSE.txt

@@ -0,0 +1,68 @@
+GNU LESSER GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+"The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+2. Conveying this Library.
+
+You may convey a copy of the Library under this License. However, if you
+modify the Library, you may not distribute your modifications without
+accompanying the distribution with complete Corresponding Source code.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,65 @@
+# Capistrano::Nextjs
+
+Next.js integration for Capistrano with systemd support.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'capistrano-nextjs'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+## Usage
+
+Add the following to your `Capfile`:
+
+```ruby
+require 'capistrano/pnpm'
+require 'capistrano/nextjs'
+install_plugin Capistrano::NextjsPlugin
+install_plugin Capistrano::NextjsSystemd
+```
+
+Add the following to your `config/deploy.rb`:
+
+```ruby
+# Next.js configuration
+set :nextjs_roles, :app
+set :nextjs_env, fetch(:stage)
+```
+
+## Available Tasks
+
+- `cap nextjs:start` - Start Next.js application
+- `cap nextjs:stop` - Stop Next.js application
+- `cap nextjs:restart` - Restart Next.js application
+- `cap nextjs:status` - Check Next.js application status
+- `cap nextjs:install` - Install systemd service
+- `cap nextjs:uninstall` - Uninstall systemd service
+- `cap nextjs:build` - Build Next.js application
+- `cap nextjs:check` - Check Next.js application (lint)
+
+## Configuration
+
+The gem automatically integrates with your deployment process:
+
+- Stops the service before deployment
+- Starts the service after successful deployment
+- Restarts the service if deployment fails
+
+## Requirements
+
+- Node.js
+- pnpm
+- systemd (for service management)
+
+## License
+
+The gem is available as open source under the terms of the [LGPL-3.0 License](https://opensource.org/licenses/LGPL-3.0).

data/lib/capistrano/nextjs/systemd.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Capistrano
+  module Nextjs
+    class Systemd < Capistrano::Plugin
+      include NextjsCommon
+      def define_tasks
+        eval_rakefile File.expand_path('../tasks/systemd.rake', __dir__)
+      end
+
+      def set_defaults
+        set_if_empty :systemctl_bin, '/bin/systemctl'
+        set_if_empty :service_unit_user, :user
+        set_if_empty :systemctl_user, fetch(:service_unit_user, :user) == :user
+
+        set_if_empty :nextjs_service_unit_name, -> { "#{fetch(:application)}_nextjs_#{fetch(:stage)}" }
+        set_if_empty :nextjs_lingering_user, -> { fetch(:lingering_user, fetch(:user)) }
+
+        ## Next.js environment variables
+        set_if_empty :nextjs_service_unit_env_files, -> { fetch(:service_unit_env_files, []) }
+        set_if_empty :nextjs_service_unit_env_vars, lambda {
+          base_vars = fetch(:service_unit_env_vars, [])
+          base_vars + ["NODE_ENV=#{fetch(:nextjs_env, 'production')}"]
+        }
+
+        set_if_empty :nextjs_service_templates_path, fetch(:service_templates_path, 'config/deploy/templates')
+      end
+
+      def systemd_command(*args)
+        command = [fetch(:systemctl_bin)]
+
+        command << '--user' unless fetch(:service_unit_user) == :system
+
+        command + args
+      end
+
+      def sudo_if_needed(*command)
+        if fetch(:service_unit_user) == :system
+          backend.sudo command.map(&:to_s).join(' ')
+        else
+          backend.execute(*command)
+        end
+      end
+
+      def execute_systemd(*)
+        sudo_if_needed(*systemd_command(*))
+      end
+    end
+  end
+end

data/lib/capistrano/nextjs/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Capistrano
+  module Nextjs
+    VERSION = '1.0.0'
+  end
+end

data/lib/capistrano/nextjs.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+begin
+  require 'capistrano/pnpm'
+rescue LoadError, RuntimeError
+  # Ignore missing pnpm dependency in test environment
+end
+
+require 'capistrano/plugin'
+
+module Capistrano
+  module NextjsCommon
+    def compiled_template(config_file = 'nextjs.yml')
+      @config_file = config_file
+      local_template_directory = fetch(:nextjs_service_templates_path)
+      search_paths = [
+        File.join(local_template_directory, 'nextjs.service.capistrano.erb'),
+        File.expand_path(
+          File.join(*%w[.. templates nextjs.service.capistrano.erb]),
+          __FILE__
+        )
+      ]
+      template_path = search_paths.detect { |path| File.file?(path) }
+      template = File.read(template_path)
+      ERB.new(template, trim_mode: '-').result(binding)
+    end
+
+    def pnpm_path
+      # Try to find pnpm in various locations
+
+      backend.capture(:which, :pnpm).strip
+    rescue StandardError
+      # Try nvm path
+      begin
+        backend.capture(:bash, '-c', 'source ~/.nvm/nvm.sh && which pnpm').strip
+      rescue StandardError
+        # Fallback to common paths
+        [
+          '/usr/local/bin/pnpm',
+          '/usr/bin/pnpm',
+          'pnpm'
+        ].each do |path|
+          return path if backend.test(:test, '-f', path) || path == 'pnpm'
+        rescue StandardError
+          next
+        end
+        'pnpm' # Ultimate fallback
+      end
+    end
+
+    def nextjs_config
+      '' # Next.js doesn't use config files like Sidekiq
+    end
+
+    def switch_user(role, &)
+      su_user = nextjs_user(role)
+      if su_user == role.user
+        yield
+      else
+        as(su_user, &)
+      end
+    end
+
+    def nextjs_user(role = nil)
+      if role.nil?
+        fetch(:nextjs_user)
+      else
+        properties = role.properties
+        properties.fetch(:nextjs_user) || # local property for nextjs only
+          fetch(:nextjs_user) ||
+          properties.fetch(:run_as) || # global property across multiple capistrano gems
+          role.user
+      end
+    end
+  end
+
+  module Nextjs
+    class Plugin < Capistrano::Plugin
+      def define_tasks
+        eval_rakefile File.expand_path('tasks/nextjs.rake', __dir__)
+      end
+
+      def set_defaults
+        set_if_empty :nextjs_default_hooks, true
+
+        set_if_empty :nextjs_env, -> { fetch(:node_env, fetch(:stage)) }
+        set_if_empty :nextjs_roles, fetch(:nextjs_role, :app)
+        set_if_empty :nextjs_configs, %w[nextjs] # basic nextjs config
+
+        set_if_empty :nextjs_log, -> { File.join(shared_path, 'log', 'nextjs.log') }
+        set_if_empty :nextjs_error_log, -> { File.join(shared_path, 'log', 'nextjs.log') }
+
+        set_if_empty :nextjs_config_files, ['nextjs.yml']
+
+        # pnpm integration
+        append :pnpm_map_bins, 'next'
+      end
+    end
+  end
+end
+
+require_relative 'nextjs/systemd'
+
+# Create top-level aliases for easier plugin installation
+module Capistrano
+  NextjsPlugin = Nextjs::Plugin
+  NextjsSystemd = Nextjs::Systemd
+end

data/lib/capistrano/tasks/nextjs.rake

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+namespace :deploy do
+  before :starting, :check_nextjs_hooks do
+    invoke 'nextjs:add_default_hooks' if fetch(:nextjs_default_hooks)
+  end
+end
+
+namespace :nextjs do
+  task :add_default_hooks do
+    after 'pnpm:install', 'nextjs:build'
+    # after 'deploy:starting', 'nextjs:quiet' if Rake::Task.task_defined?('nextjs:quiet')
+    after 'deploy:updated', 'nextjs:stop'
+    after 'deploy:published', 'nextjs:start'
+    after 'deploy:failed', 'nextjs:restart'
+  end
+
+  desc 'Build Next.js application'
+  task :build do
+    on roles fetch(:nextjs_roles) do
+      within release_path do
+        execute :pnpm, 'build'
+      end
+    end
+  end
+
+  desc 'Check Next.js application'
+  task :check do
+    on roles fetch(:nextjs_roles) do
+      within current_path do
+        execute :pnpm, 'lint'
+      end
+    end
+  end
+end

data/lib/capistrano/tasks/systemd.rake

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+git_plugin = self
+
+namespace :nextjs do
+  standard_actions = {
+    start: 'Start Next.js',
+    stop: 'Stop Next.js (graceful shutdown)',
+    status: 'Get Next.js Status',
+    restart: 'Restart Next.js'
+
+  }
+  standard_actions.each do |command, description|
+    desc description
+    task command do
+      on roles fetch(:nextjs_roles) do |role|
+        git_plugin.switch_user(role) do
+          git_plugin.config_files(role).each do |config_file|
+            git_plugin.execute_systemd(command, git_plugin.nextjs_service_file_name(config_file))
+          end
+        end
+      end
+    end
+  end
+
+  desc 'Stop Next.js gracefully'
+  task :quiet do
+    on roles fetch(:nextjs_roles) do |role|
+      git_plugin.switch_user(role) do
+        git_plugin.stop_nextjs_gracefully(role)
+      end
+    end
+  end
+
+  desc 'Install Next.js systemd service'
+  task :install do
+    on roles fetch(:nextjs_roles) do |role|
+      git_plugin.switch_user(role) do
+        git_plugin.create_systemd_template(role)
+      end
+    end
+    invoke 'nextjs:enable'
+  end
+
+  desc 'Uninstall Next.js systemd service'
+  task :uninstall do
+    invoke 'nextjs:disable'
+    on roles fetch(:nextjs_roles) do |role|
+      git_plugin.switch_user(role) do
+        git_plugin.rm_systemd_service(role)
+      end
+    end
+  end
+
+  desc 'Enable Next.js systemd service'
+  task :enable do
+    on roles(fetch(:nextjs_roles)) do |role|
+      git_plugin.config_files(role).each do |config_file|
+        git_plugin.execute_systemd('enable', git_plugin.nextjs_service_file_name(config_file))
+      end
+
+      if fetch(:systemctl_user) && fetch(:nextjs_lingering_user)
+        execute :loginctl, 'enable-linger', fetch(:nextjs_lingering_user)
+      end
+    end
+  end
+
+  desc 'Disable Next.js systemd service'
+  task :disable do
+    on roles(fetch(:nextjs_roles)) do |role|
+      git_plugin.config_files(role).each do |config_file|
+        git_plugin.execute_systemd('disable', git_plugin.nextjs_service_file_name(config_file))
+      end
+    end
+  end
+
+  def fetch_systemd_unit_path
+    if fetch(:nextjs_systemctl_user) == :system
+      '/etc/systemd/system/'
+    else
+      home_dir = backend.capture :pwd
+      File.join(home_dir, '.config', 'systemd', 'user')
+    end
+  end
+
+  def create_systemd_template(role)
+    systemd_path = fetch(:service_unit_path, fetch_systemd_unit_path)
+    backend.execute :mkdir, '-p', systemd_path if fetch(:systemctl_user)
+
+    config_files(role).each do |config_file|
+      ctemplate = compiled_template(config_file)
+      temp_file_name = File.join('/tmp', "nextjs.#{config_file}.service")
+      systemd_file_name = File.join(systemd_path, nextjs_service_file_name(config_file))
+      backend.upload!(StringIO.new(ctemplate), temp_file_name)
+      if fetch(:systemctl_user)
+        warn "Moving #{temp_file_name} to #{systemd_file_name}"
+        backend.execute :mv, temp_file_name, systemd_file_name
+      else
+        warn "Installing #{systemd_file_name} as root"
+        backend.execute :sudo, :mv, temp_file_name, systemd_file_name
+      end
+    end
+  end
+
+  def rm_systemd_service(role)
+    systemd_path = fetch(:service_unit_path, fetch_systemd_unit_path)
+
+    config_files(role).each do |config_file|
+      systemd_file_name = File.join(systemd_path, nextjs_service_file_name(config_file))
+      if fetch(:systemctl_user)
+        warn "Deleting #{systemd_file_name}"
+        backend.execute :rm, '-f', systemd_file_name
+      else
+        warn "Deleting #{systemd_file_name} as root"
+        backend.execute :sudo, :rm, '-f', systemd_file_name
+      end
+    end
+  end
+
+  def stop_nextjs_gracefully(role)
+    config_files(role).each do |config_file|
+      nextjs_service = nextjs_service_unit_name(config_file)
+      warn "Stopping #{nextjs_service} gracefully"
+      execute_systemd('stop', nextjs_service)
+    end
+  end
+
+  def nextjs_service_unit_name(config_file)
+    if config_file == 'nextjs.yml'
+      fetch(:nextjs_service_unit_name)
+    else
+      "#{fetch(:nextjs_service_unit_name)}.#{config_file.split('.')[0..-2].join('.')}"
+    end
+  end
+
+  def nextjs_service_file_name(config_file)
+    ## Remove the extension
+    config_file = config_file.split('.').join('.')
+
+    "#{nextjs_service_unit_name(config_file)}.service"
+  end
+
+  def config_files(role)
+    role.properties.fetch(:nextjs_config_files) ||
+      fetch(:nextjs_config_files)
+  end
+end

data/lib/capistrano/templates/nextjs.service.capistrano.erb

@@ -0,0 +1,23 @@
+
+[Unit]
+Description=Next.js for <%= "#{fetch(:application)} (#{fetch(:stage)})" %>
+# start us only once the network and logging subsystems are available
+After=syslog.target network.target
+
+[Service]
+Type=simple
+<%="User=#{nextjs_user}" if fetch(:nextjs_systemctl_user) == :system %>
+WorkingDirectory=<%= current_path %>
+ExecStart=/bin/bash -l -c 'pnpm start'
+ExecReload=/bin/kill -TSTP $MAINPID
+ExecStop=/bin/kill -SIGTERM $MAINPID
+
+Restart=always
+
+
+StandardOutput=file:<%= shared_path %>/log/nextjs.log
+StandardError=file:<%= shared_path %>/log/nextjs-error.log
+
+SyslogIdentifier=<%= nextjs_service_unit_name(@config_file) %>
+[Install]
+WantedBy=default.target

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: capistrano-nextjs
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Florian Crusius
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capistrano
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.9.0
+- !ruby/object:Gem::Dependency
+  name: capistrano-pnpm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: Next.js integration for Capistrano with systemd support, enabling automated
+  deployment and service management for Next.js applications using pnpm
+email:
+- florian@zauberware.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/capistrano/nextjs.rb
+- lib/capistrano/nextjs/systemd.rb
+- lib/capistrano/nextjs/version.rb
+- lib/capistrano/tasks/nextjs.rake
+- lib/capistrano/tasks/systemd.rake
+- lib/capistrano/templates/nextjs.service.capistrano.erb
+homepage: https://github.com/zauberware/capistrano-nextjs
+licenses:
+- LGPL-3.0
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.7
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Next.js integration for Capistrano
+test_files: []