Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mattbrictson/capistrano-mb
[unmaintained] Capistrano tasks for deploying Rails from scratch to Ubuntu 16.04 and 18.04
https://github.com/mattbrictson/capistrano-mb
capistrano devops rails ruby systemd ubuntu unmaintained vps
Last synced: about 1 month ago
JSON representation
[unmaintained] Capistrano tasks for deploying Rails from scratch to Ubuntu 16.04 and 18.04
- Host: GitHub
- URL: https://github.com/mattbrictson/capistrano-mb
- Owner: mattbrictson
- License: mit
- Archived: true
- Created: 2013-08-21T23:41:45.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2019-11-09T17:14:56.000Z (about 5 years ago)
- Last Synced: 2024-05-18T20:48:03.171Z (7 months ago)
- Topics: capistrano, devops, rails, ruby, systemd, ubuntu, unmaintained, vps
- Language: Ruby
- Homepage:
- Size: 282 KB
- Stars: 118
- Watchers: 7
- Forks: 24
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
⚠️ **This project is no longer maintained.** Thanks for your interest in capistrano-mb. I don't use this gem anymore and so I've chosen not to support it going forward. However, many of the lessons I've learned from building capistrano-mb I am now applying to a new project called [tomo](https://github.com/mattbrictson/tomo). Hope to see you there!
---
# capistrano-mb
**An opinionated Capistrano task library for deploying Rails apps from scratch on Ubuntu 16.04 or 18.04 LTS.**
[](https://rubygems.org/gems/capistrano-mb)
Capistrano is great for deploying Rails applications, but what about all the prerequisites, like Nginx and PostgreSQL? Do you have a firewall configured on your VPS? Have you installed the latest OS security updates? Is HTTPS working right?
The capistrano-mb gem adds a `cap provision` task to Capistrano that takes care of all that. Out of the box, `provision` will:
* Install the latest `postgresql`, `node.js`, and `nginx` apt packages
* Install all libraries needed to build Ruby
* Lock down your VPS using `ufw` (a simple front-end to iptables)
* Set up `logrotated` for your Rails logs
* Schedule an automatic daily backup of your Rails database
* Generate a self-signed SSL certificate if you need one
* Set up ngnix with the latest SSL practices and integrate it with Unicorn for your Rails app
* Create the `deployer` user and install an SSH public key
* Install `rbenv` and use `ruby-build` to compile the version of Ruby required by your app (by inspecting your `.ruby-version` file)
* And more!
The gem is named "capistrano-mb" because it is prescribes my ([@mattbrictson](https://github.com/mattbrictson)) personal preferences for automating deployments of Rails projects. I've worked several years as a freelance developer juggling lots of Rails codebases, so its important for me to have a good, consistent server configuration. You'll notice that capistrano-mb is opinionated and strictly uses the following stack:
* Ubuntu 16.04 or 18.04 LTS
* PostgreSQL
* Unicorn
* Nginx
* rbenv
* dotenv
In addition, capistrano-mb changes many of Capistrano's defaults, including the deployment location, Bundler behavior, and SSH keep-alive settings. (See [defaults.rake][] for details.)
Not quite to your liking? Consider forking the project to meet your needs.
## Roadmap
I plan to continue maintaining this project for the benefit of deploying my own Rails apps for the foreseeable future. In practice, this means a new version or two per year. The behavior of capistrano-mb may change as I upgrade my apps to new versions of Rails. For example, at some point I might:
* Replace Unicorn with Puma
* Switch from dotenv to encrypted credentials
* Add Let's Encrypt
* Use a more robust database backup solution
*Future changes in capistrano-mb are not guaranteed to have graceful migration paths, so I recommend pinning your Gemfile dependency to a specific version and upgrading with extreme care.*
## Quick start
Please note that this project requires **Capistrano 3.x**, which is a complete rewrite of Capistrano 2.x. The two major versions are not compatible.
### 1. Purchase an Ubuntu 16.04 or 18.04 VPS
To use capistrano-mb, you'll need a clean **Ubuntu 16.04 or 18.04** server to deploy to. The only special requirement is that your public SSH key must be installed on the server for the `root` user.
Test that you can SSH to the server as `root` without being prompted for a password. If that works, capistrano-mb can take care of the rest. You're ready to proceed!
### 2. .ruby-version
capistrano-mb needs to know the version of Ruby that your app requires, so that it can install Ruby during the provisioning process. Place a `.ruby-version` file in the root of your project containing the desired version, like this:
```
2.5.0
```
*If you are using `rbenv`, just run `rbenv local 2.5.0` and it will create this file for you.*
### 3. Gemfile
capistrano-mb makes certain assumptions about your Rails app, namely that it uses [dotenv][] to manage Rails secrets via environment variables, and that it runs on top of PostgreSQL and [unicorn][]. Make sure they are specified in the Gemfile:
```ruby
gem "dotenv-rails", ">= 2.0.0"
gem "pg", "~> 0.18"
gem "unicorn"
```
Then for the capistrano-mb tools themselves, add these gems to the development group:
```ruby
group :development do
gem "capistrano-bundler", :require => false
gem "capistrano-rails", :require => false
gem "capistrano", "~> 3.10", :require => false
gem "capistrano-mb", "~> 0.35.0", :require => false
end
```
And then execute:
```
$ bundle install
```
### 4. cap install
If your project doesn't yet have a `Capfile`, run `cap install` with the list of desired stages (environments). For simplicity, this installation guide will assume a single production stage:
```
bundle exec cap install STAGES=production
```
### 5. Capfile
Add these lines to the **bottom** of your app's `Capfile` (order is important!):
```ruby
require "capistrano/bundler"
require "capistrano/rails"
require "capistrano/mb"
```
### 6. deploy.rb
Modify `config/deploy.rb` to set the specifics of your Rails app. At the minimum, you'll need to set these two options:
```ruby
set :application, "my_app_name"
set :repo_url, "[email protected]:username/repository.git"
```
### 7. production.rb
Modify `config/deploy/production.rb` to specify the IP address of your production server. In this example, I have a single 1GB VPS (e.g. at DigitalOcean) that plays all the roles:
```ruby
server "my.production.ip",
:user => "deployer",
:roles => %w[app backup cron db web]
```
*Note that you must include the `backup` and `cron` roles if you want to make use of capistrano-mb's database backups and crontab features.*
### 8. secrets.yml
Your Rails apps may have a `config/secrets.yml` file that specifies the Rails secret key. capistrano-mb configures dotenv to provide this secret in a `RAILS_SECRET_KEY_BASE` environment variable. You'll therefore need to modify `secrets.yml` as follows:
```ruby
production:
secret_key_base: <%= ENV["RAILS_SECRET_KEY_BASE"] %>
```
### 9. Provision and deploy!
Run capistrano-mb's `provision` task. This will ask you a few questions, install Ruby, PostgreSQL, Nginx, etc., and set everything up. The entire process takes about 10 minutes (mostly due to compiling Ruby from source).
```
bundle exec cap production provision
```
Once that's done, your app is now ready to deploy!
```
bundle exec cap production deploy
```
## Advanced usage
### Choosing which recipes to auto-run
Most of the capistrano-mb recipes are designed to run automatically as part of `cap provision`, for installing and setting up various bits of the Rails infrastructure, like nginx, unicorn, and postgres. Some recipes also contribute to the `cap deploy` process.
*This auto-run behavior is fully under your control.* In your `deploy.rb`, set `:mb_recipes` to an array of the desired recipes. If you don't want a recipe to execute as part of `deploy`/`provision`, simply omit it from the list.
The following list will suffice for most out-of-the-box Rails apps. The order of the list is not important.
```ruby
set :mb_recipes, %w[
aptitude
bundler
crontab
dotenv
logrotate
migrate
nginx
postgresql
rbenv
seed
ssl
ufw
unicorn
user
version
]
```
Even if you don't include a recipe in the auto-run list, you can still invoke the tasks of those recipes manually at your discretion. Run `bundle exec cap -T` to see the full list of tasks.
### Configuration
Many of the recipes have default settings that can be overridden. Use your
`deploy.rb` file to specify these overrides. Or, you can override per stage.
Here is an example override:
set :mb_unicorn_workers, 8
For the full list of settings and their default values, refer to [defaults.rake][].
## Further reading
Check out my [rails-template][] project, which generates Rails applications with capistrano-mb pre-configured and ready to go.
## History
This gem used to be called `capistrano-fiftyfive`. If you are upgrading from capistrano-fiftyfive, refer to the [CHANGELOG entry for v0.22.0](CHANGELOG.md#0220-2015-06-22) for migration instructions.
As of 0.33.0, capistrano-mb no longer supports Ubuntu 12.04 or 14.04. If your server runs one of these older versions, use [capistrano-mb 0.32.0](https://github.com/mattbrictson/capistrano-mb/tree/v0.32.0).
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
[Postmark]:https://postmarkapp.com
[cast337]:http://railscasts.com/episodes/337-capistrano-recipes
[cast373]:http://railscasts.com/episodes/373-zero-downtime-deployment
[defaults.rake]:lib/capistrano/tasks/defaults.rake
[rails-template]:https://github.com/mattbrictson/rails-template/
[dotenv]:https://github.com/bkeepers/dotenv
[unicorn]:http://unicorn.bogomips.org/