Tomo is a friendly command-line tool for deploying Rails apps. It is a new alternative to Capistrano, Mina, and Shipit that optimizes for simplicity and developer happiness.
This project wouldn't be possible without the generosity of the open source Ruby community. Please support open source projects and your fellow developers by helping answer questions, contributing pull requests to improve code and documentation, or just drop a note to say thanks!
Tomo is distributed as a ruby gem. To install:
$ gem install tomo
An easy way to kick the tires is to view the
Configuring a project
Let’s init a project to see how tomo is configured.
.tomo/config.rb file defines all the settings and tasks needed to setup and deploy a typical Rails project. An abbreviated version looks like this:
# .tomo/config.rb plugin "git" plugin "bundler" plugin "rails" # ... host "email@example.com" set application: "my-rails-app" set deploy_to: "/var/www/%<application>" set git_url: "firstname.lastname@example.org:my-username/my-rails-app.git" set git_branch: "master" # ... setup do run "git:clone" run "git:create_release" run "bundler:install" run "rails:db_schema_load" # ... end deploy do run "git:create_release" run "core:symlink_shared" run "core:write_release_json" run "bundler:install" run "rails:assets_precompile" run "rails:db_migrate" run "core:symlink_current" # ... end
Eventually you'll want to edit the config file to specify the appropriate user and host, perhaps define some custom tasks, and tweak the settings to make them suitable for your Rails app. You can also take advantage of more advanced features like multiple hosts and environment-based config.
With tomo, an initial deployment is separated into two distinct steps. The
setup command prepares the host for its first deploy. Let’s take a look at the documentation with
We can simulate the setup operation with the
--dry-run option. Let's try it:
As you can see, the setup command in this project clones the git repository, installs ruby, node, bundler, and initializes the database. One the host is set up, it is ready for its first deploy.
Performing a deploy
Typically you only need to run
setup once. From then on deploying a project is a matter of running the
setup, this can be simulated with
--dry-run, like this:
Running a single task
Tomo can also
run individual remote tasks. Use the
tasks command to see the list of tasks tomo knows about.
One of the built-in Rails tasks is
rails:console, which brings up a fully-interactive Rails console over SSH. We can simulate this with
--dry-run as well.
Tomo has many plugins built-in, but you can easily add your own to extend tomo with custom tasks. By convention, custom plugins are stored in
.tomo/plugins/. These plugins can define tasks as plain ruby methods. For example:
# .tomo/plugins/my-plugin.rb def hello remote.run "echo", "hello", settings[:application] end
remote.run to execute shell scripts on the remote host, similar to how you would use Ruby's
system. Project settings are accessible via
settings, which is a plain Ruby hash.
Load your plugin in
config.rb like this:
# .tomo/config.rb plugin "./plugins/my-plugin.rb"
And run it!
And just like that, you are now already familiar with the basics of tomo and how to extend it! Tomo is even more friendly and powerful with the help of bash completions. If you use bash, run
tomo completion-script for instructions on setting them up.
To prepare your existing project for a real deploy, check out the sections of the reference documentation on configuration, writing custom tasks [TODO], the setup command, and the deploy command. There is also a tutorial that walks through deploying a new Rails app from scratch [TODO]. If you have questions, check out the FAQ and support notes below. Enjoy using tomo!
What does the
unsupported option "accept-new" error mean?
By default, tomo uses the "accept-new" value for the StrictHostKeyChecking option, which is supported by OpenSSH 7.6 and newer. If you are using an older version, this will cause an error. As a workaround, you can override tomo's default behavior like this:
# Replace "accept-new" with something compatible with older versions of SSH set ssh_strict_host_key_checking: true # or false
Thanks for your interest in Tomo! I use Tomo myself to deploy my own Rails projects and intend to keep this repository working and up to date for the foreseeable future. However Tomo is only a hobby, and as the sole maintainer, my ability to provide support and review pull request is limited and a bit sporadic. My priorities right now are:
- Improve test coverage
- Keep the project free of any serious bugs
- Stay up to date with the latest versions of Ruby and gem dependencies
If you'd like to help by submitting a pull request, that would be much appreciated! Check out the contribution guide to get started.
Otherwise if you want to report a bug, or have ideas, feedback or questions about Tomo, let me know via GitHub issues and I will do my best to provide a helpful answer. Happy hacking! —Matt
The gem is available as open source under the terms of the MIT License.
Code of conduct
Everyone interacting in the Tomo project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.