# Capistrano — Remote Multi-Server Deployment Automation

> Automate deployments to multiple servers over SSH with a Ruby-based DSL for defining release workflows, rollbacks, and task orchestration.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Capistrano — Remote Multi-Server Deployment Automation

## Quick Use
```bash
gem install capistrano
cap install
# edit config/deploy.rb and config/deploy/production.rb
cap production deploy
```

## Introduction
Capistrano is a remote server automation tool that executes commands in parallel across multiple machines over SSH. Originally built for deploying Ruby on Rails applications, it has grown into a general-purpose deployment framework used across many language ecosystems for orchestrating release workflows.

## What Capistrano Does
- Deploys application code to one or many servers simultaneously over SSH
- Maintains a release directory structure with symlinked shared files
- Provides instant rollback to any previous release with a single command
- Executes arbitrary tasks on remote servers in parallel or sequentially
- Integrates with version control to pull code directly onto target servers

## Architecture Overview
Capistrano runs on a local workstation and connects to remote servers via SSH using the SSHKit library. Deployments follow a directory convention with releases, current, and shared directories. Each deploy creates a new timestped release folder, updates symlinks, and runs hook tasks defined in a Ruby DSL. The framework is built around a Rake-like task system with before/after hooks for customization.

## Self-Hosting & Configuration
- Requires Ruby 2.5+ on the local machine; servers only need SSH and a POSIX shell
- Define server roles (web, app, db) in stage-specific configuration files
- Set shared files and directories that persist across releases via `linked_files` and `linked_dirs`
- Customize the number of releases to keep with `set :keep_releases, 5`
- Add plugins for Bundler, Rails migrations, rbenv, or custom integrations

## Key Features
- Parallel execution across server groups with role-based filtering
- Atomic symlink switching for zero-downtime deployments
- Built-in rollback with `cap production deploy:rollback`
- Extensible plugin ecosystem for Bundler, Passenger, Puma, and systemd
- Dry-run mode to preview commands without executing them

## Comparison with Similar Tools
- **Ansible** — agentless automation for full infrastructure management; Capistrano focuses specifically on application deployment
- **Kamal** — Docker-based deployment from Basecamp; Capistrano deploys source code directly without containers
- **Fabric** — Python SSH task runner; Capistrano provides more deployment-specific conventions out of the box
- **Deployer** — PHP deployment tool inspired by Capistrano; Capistrano targets Ruby and polyglot stacks
- **Mina** — faster single-command SSH deploys; Capistrano offers richer role-based multi-server orchestration

## FAQ
**Q: Can I use Capistrano for non-Ruby projects?**
A: Yes. Capistrano is a general-purpose SSH task runner; many teams use it for Python, PHP, and Node.js deployments.

**Q: How does rollback work?**
A: Capistrano keeps previous release directories intact and simply re-points the current symlink to a prior release.

**Q: Does Capistrano require an agent on the server?**
A: No. It only needs SSH access and a standard POSIX shell on the target servers.

**Q: Can I run Capistrano in CI/CD pipelines?**
A: Yes. Configure SSH keys in your CI environment and invoke cap commands as build steps.

## Sources
- https://github.com/capistrano/capistrano
- https://capistranorb.com

---
Source: https://tokrepo.com/en/workflows/capistrano-remote-multi-server-deployment-automation-a8fedcee
Author: Script Depot