|
| 1 | +# Capistrano Configuration |
| 2 | + |
| 3 | +[Capistrano](https://capistranorb.com/) is a tool for configuring and deploying web apps. |
| 4 | + |
| 5 | +Widely used in the Ruby on Rails world, Capistrano provides utilities to deploy RoR apps with a Ruby DSL but getting it right the first time might be a headacher for many. |
| 6 | + |
| 7 | +This section is a noble quest to make configuring Capistrano easier. |
| 8 | + |
| 9 | +## Version and Useful plugins |
| 10 | + |
| 11 | +If possible, always try to use latest Capistrano version. Old version configurations were very hard to complete and needed a lot of coding in the Capistrano DSL. |
| 12 | + |
| 13 | +Newer versions simplify this a lot. Current version as of today is 3.11.0. |
| 14 | + |
| 15 | +### Plugins |
| 16 | + |
| 17 | +Capistrano by itself is very useful but complemented with plugins can make your deployments very simple. |
| 18 | + |
| 19 | +When you install Capistrano, in the `Capfile` there's a list of suggested plugins: |
| 20 | + |
| 21 | +- [Capistrano RVM](https://github.com/capistrano/rvm) |
| 22 | +- [Capistrano rbenv](https://github.com/capistrano/rbenv) |
| 23 | +- [Capistrano ChRuby](https://github.com/capistrano/chruby) |
| 24 | +- [Capistrano Bundler](https://github.com/capistrano/bundler) |
| 25 | +- [Capistrano Rails](https://github.com/capistrano/rails) |
| 26 | +- [Capistrano Passenger](https://github.com/capistrano/passenger) |
| 27 | + |
| 28 | +I also suggest the following ones: |
| 29 | + |
| 30 | +- [Capistrano Nginx](https://github.com/ivalkeen/capistrano-nginx) |
| 31 | +- [Capistrano Sidekiq](https://github.com/seuros/capistrano-sidekiq) |
| 32 | +- [Capistrano Puma](https://github.com/seuros/capistrano-puma) |
| 33 | + |
| 34 | +Every plugin provides a set of commands to be run when configuring, before deployment, during deployment, and after deployment. |
| 35 | + |
| 36 | +All the commands you'd normally would execute in the server can be automated with these extensions. |
| 37 | + |
| 38 | +For Rails apps, you normally should have these installed and enabled in your project's `Capfile`. |
| 39 | + |
| 40 | +- [Capistrano RVM](https://github.com/capistrano/rvm) |
| 41 | +- [Capistrano Bundler](https://github.com/capistrano/bundler) |
| 42 | +- [Capistrano Rails](https://github.com/capistrano/rails) |
| 43 | +- [Capistrano Nginx](https://github.com/ivalkeen/capistrano-nginx) |
| 44 | + |
| 45 | +Those are the basic ones. If your app uses Sidekiq, well, use the Capistrano Sidekiq plugin as well. |
| 46 | + |
| 47 | +> Note: you could skip using Capistrano RVM and installing RVM on your server but I highly suggest using a Ruby version manager because using the default in the machine can lead to trouble because it belongs to `root` user. |
| 48 | +> |
| 49 | +> With Capistrano, you'd want to avoid anything that has to be with user `root`. |
| 50 | +
|
| 51 | +## Checklist |
| 52 | + |
| 53 | +In order for Capistrano to work, you need the following configured/installed: |
| 54 | + |
| 55 | +- RVM |
| 56 | +- Ruby |
| 57 | +- Bundler |
| 58 | +- Environment Variables |
| 59 | +- Not-root system user(example, ubuntu in AWS) |
| 60 | +- Access to private repo(if code is in private repository) |
| 61 | + |
| 62 | +The first three ones are real simple. In this project you can find commands to install them. However, the last point, is the tricky one. |
| 63 | + |
| 64 | +## Why Does Capistrano need access to my private repo? |
| 65 | + |
| 66 | +You'd see, the process of Capistrano is quite simple. As you should've already noticed, Capistrano is a tool for automation. Automation is taking a set of scripts and running them without you having to intervine. |
| 67 | + |
| 68 | +> An example of a script can be any of the ones you'd find in this repo. |
| 69 | +
|
| 70 | +As such, Capistrano runs a set of commands, in a given order, to setup and deploy your Rails app to the server. |
| 71 | + |
| 72 | +So, How do you normally keep your app in the server up to date? You have to pull changes from your repo. If it's a private one, you'd need access to it. |
| 73 | + |
| 74 | +The easiest way is by setting an SSH-key [1][ssh-bitbucket] [2][ssh-github] [3][multi-git]. |
| 75 | + |
| 76 | +> The other option is letting the password prompt appear but that one is not automatable. |
| 77 | +
|
| 78 | +## Letting Capistrano pull changes from private repo |
| 79 | + |
| 80 | +After generating a new SSH-key [1][ssh-bitbucket] [2][ssh-github] [3][multi-git] and setting it up in your repo, do the following. |
| 81 | + |
| 82 | +> Ideally, you should have all your ssh keys under folder |
| 83 | +> |
| 84 | +> `/home/ubuntu/.ssh` or `~/.ssh` |
| 85 | +> |
| 86 | +> to easily reference the keys everywhere |
| 87 | +
|
| 88 | +In `~/.ssh` create a file called `config` and opening with a text editor, this case, nano. |
| 89 | + |
| 90 | +```bash |
| 91 | +$ touch ~/.ssh/config |
| 92 | +$ nano ~/.ssh/config |
| 93 | +``` |
| 94 | + |
| 95 | +In order to connect to the repository without specifying the key, one of the steps in the [Multi git][multi-git] setup is what we need: |
| 96 | + |
| 97 | +### For GitHub |
| 98 | + |
| 99 | +```bash |
| 100 | +Host github.com |
| 101 | + Hostname github.com |
| 102 | + IdentityFile /home/ubuntu/.ssh/[THE-KEY-YOU-GENERATED] |
| 103 | + User git |
| 104 | +``` |
| 105 | + |
| 106 | +Test it with `ssh -t [email protected]` |
| 107 | + |
| 108 | +### For Bitbucket |
| 109 | + |
| 110 | +```bash |
| 111 | +Host bitbucket.org |
| 112 | + Hostname bitbucket.org |
| 113 | + IdentityFile /home/ubuntu/.ssh/[THE-KEY-YOU-GENERATED] |
| 114 | + User git |
| 115 | +``` |
| 116 | + |
| 117 | +Test it with `ssh -t [email protected]` |
| 118 | + |
| 119 | +The test result is a greeting message indicating that you cannot log in in the service(github or bitbucket) via command line. |
| 120 | + |
| 121 | +When you get this step right, you're closer to have Capistrano working for you. |
| 122 | + |
| 123 | +In fact, these crucial step is the one that would bug you more if you don't get it right at the beginning. |
| 124 | + |
| 125 | +## Configuration in Capistrano Files |
| 126 | + |
| 127 | +You also need to indicate certaing things to Capistrano in your local repo. |
| 128 | + |
| 129 | +We need to add things to `deploy.rb` and `[ENVIRONTMENT].rb` |
| 130 | + |
| 131 | +``` |
| 132 | +├── Capfile |
| 133 | +├── config |
| 134 | +│ ├── deploy |
| 135 | +│ │ ├── production.rb |
| 136 | +│ │ └── staging.rb |
| 137 | +│ └── deploy.rb |
| 138 | +└── lib |
| 139 | + └── capistrano |
| 140 | + └── tasks |
| 141 | +``` |
| 142 | + |
| 143 | +In this case, we're going to touch `production.rb`. |
| 144 | + |
| 145 | +You have to make sure that the setting `repo_url` is using the git version of the URL to your repo. |
| 146 | + |
| 147 | +Every repo can have to ways of being cloned. One is via HTTP and the other one is with the Git protocol: |
| 148 | + |
| 149 | +- `[email protected]:otroespacioweb/letom-api.git` |
| 150 | +- `https://[email protected]/devaspros/letom-api.git` |
| 151 | + |
| 152 | +For Capistrano purposes, we need to use the git version to connect via SSH. |
| 153 | + |
| 154 | +You also need to make sure that `use_sudo` is set to `false`. |
| 155 | + |
| 156 | +Finally, the option `ssh_options` should be configured to connect to the server via SSH. |
| 157 | + |
| 158 | +So, in `deploy.rb` file somewhere you should have: |
| 159 | + |
| 160 | +```ruby |
| 161 | +# ... |
| 162 | + |
| 163 | +set :repo_url, "[email protected]:otroespacioweb/letom-api.git" |
| 164 | + |
| 165 | +# ... |
| 166 | +``` |
| 167 | + |
| 168 | +and in your environment specific file: |
| 169 | + |
| 170 | +```ruby |
| 171 | +# ... |
| 172 | + |
| 173 | +set :ssh_options, { |
| 174 | + user: 'ubuntu', |
| 175 | + keys: %w[~/.ssh/letom-us-east-1.pem], |
| 176 | + forward_agent: false |
| 177 | +} |
| 178 | + |
| 179 | +# ... |
| 180 | +``` |
| 181 | + |
| 182 | +The `keys` key in the hash is a path to the folder where the SSH key to connect to the server is. |
| 183 | + |
| 184 | +With this option is that Capistrano can login to your server and run everything needed to the app to be deployed: |
| 185 | + |
| 186 | +- Check folders are created |
| 187 | +- Pull repo |
| 188 | +- Run bundle install |
| 189 | +- Run migrations |
| 190 | +- Precompile assets |
| 191 | +- Symlink folders |
| 192 | +- Restart application(s) |
| 193 | +- etc |
| 194 | + |
| 195 | +## Conclusion |
| 196 | + |
| 197 | +Hopefully, this guide will server the purpose of making easier to configure deployment of Rails apps with Capistrano. |
| 198 | + |
| 199 | +[ssh-bitbucket]: https://confluence.atlassian.com/bitbucket/set-up-an-ssh-key-728138079.html |
| 200 | +[ssh-github]: https://help.github.com/en/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent |
| 201 | +[multi-git]: https://gist.github.com/cesc1989/ce791228177867271147770629fe754b |
0 commit comments