Tomo

Tomo is a friendly command-line tool for deploying Rails apps.

💻 Rich command-line interface with built-in bash completions
☁️ Multi-environment and role-based multi-host support
💎 Everything you need to deploy a basic Rails app out of the box
🔌 Easily extensible for polyglot projects (not just Rails!)
📚 Quality documentation
🔬 Minimal dependencies

→ See how tomo compares to other Ruby deployment tools like Capistrano and Mina.

• Quick start
• Usage
• Extending tomo
• Tutorials
• Reference documentation
• FAQ
• Support
• License
• Code of conduct
• Contribution guide

Quick start

Installation

Tomo is distributed as a ruby gem. To install:

$ gem install tomo

💡 Protip: run

tomo completion-script

for instructions on setting up bash completions.

Configuring a project

Tomo is configured via a

.tomo/config.rb

tomo init

An abbreviated version looks like this:

# .tomo/config.rb

plugin "git"
plugin "bundler"
plugin "rails"
...
host "[email protected]"
set application: "my-rails-app"
set deploy_to: "/var/www/%{application}"
set git_url: "[email protected]:my-username/my-rails-app.git"
set git_branch: "main"
...
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

Next steps

→ The reference docs have a complete guide to tomo configuration.
→ Check out the Deploying Rails From Scratch tutorial for a step-by-step guide to using tomo with a real app.

Usage

Once your project is configured, you can:

1. Run

   tomo setup

   to prepare the remote host for its first deploy.
2. Run

   tomo deploy

   to deploy your app.
3. Use

   tomo run

   to invoke one-off tasks, like launching a Rails console.

💡 Protip: add

-h

or

--help

when running any of these commands to see detailed docs and examples.

tomo setup

tomo setup

setup

.tomo/config.rb

Out of the box, tomo will:

• Configure necessary environment variables, like

  RAILS_ENV

  and

  SECRET_KEY_BASE

• Install Ruby, Bundler, Node, Yarn, and dependencies
• Create all necessary deployment directories
• Create the Rails database, load the schema, and insert seed data

→ Here is the default list of tasks invoked by the setup command.
→ The

tomo setup

tomo deploy

Whereas

tomo setup

tomo deploy

deploy

.tomo/config.rb

1. Create a release (using the git:create_release task)
2. Build the project (e.g. bundler:install, rails:assets_precompile)
3. Migrate data to the meet the requirements of the new release (e.g. rails:db_migrate)
4. Make the new release the "current" one (core:symlink_current)
5. Restart the app to use the new current release (e.g. puma:restart)
6. Perform any cleanup (e.g. bundler:clean)

💡 Protip: you can abbreviate tomo commands, like

tomo d

for

tomo deploy

or

tomo s

for

tomo setup

.

→ Here is the default list of tasks invoked by the deploy command.
→ The

tomo deploy

--dry-run

tomo run [TASK]

Tomo can also

run

tasks

One of the built-in Rails tasks is

rails:console

💡 Protip: you can shorten this as

tomo rails:console

(the

run

command is implied).

→ The

tomo run

Extending tomo

Tomo has a powerful plugin system that lets you extend tomo by installing Ruby gems (e.g. tomo-plugin-sidekiq). You can also define plugins on the fly within your project by adding simple

.rb

.tomo/plugins/

# .tomo/plugins/my-plugin.rb

def hello
  remote.run "echo", "hello", settings[:application]
end

Load your plugin in

config.rb

# .tomo/config.rb

plugin "./plugins/my-plugin.rb"

And run it!

→ The Writing Custom Tasks tutorial has an in-depth explanation of how plugins work.
→ The TaskLibrary API is tomo's DSL for building tasks.
→ The Publishing a Plugin tutorial explains how to package your plugin as a Ruby gem to share it with the community.

Tutorials

• Deploying Rails From Scratch
• Writing Custom Tasks
• Publishing a Plugin

Reference documentation

• Configuration
• Commands
  • init
  • setup
  • deploy
  • run
  • tasks
• Plugins
  • core
  • bundler
  • env
  • git
  • nodenv
  • puma
  • rails
  • rbenv
• API
  • Host
  • Logger
  • Paths
  • PluginDSL
  • Remote
  • Result
  • TaskLibrary
  • Testing::MockPluginTester

FAQ

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

Can I deploy multiple apps to a single host?

Tomo relies on the host user's bash profile for various things, like setting environment variables and initializing rbenv and nodenv. This makes it impractical to deploy multiple apps to a single host using the same deploy user.

The solution is to create multiple users on the remote host, and then configure a different user for deploying each app. That way each user can have its own distinct environment variables and you can easily configure each app differently without risking conflicts. Refer to the tomo Rails tutorial for instructions on creating a deploy user.

E.g. app1 would be configured to deploy as:

host "[email protected]"

And app2 would be configured to deploy as:

host "[email protected]"

Next run

tomo setup

Support

This project is a labor of love and I can only spend a few hours a week maintaining it, at most. If you'd like to help by submitting a pull request, or if you've discovered a bug that needs my attention, please let me know. Check out CONTRIBUTING.md to get started. Happy hacking! —Matt

License

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.

Contribution guide

Interested in filing a bug report, feature request, or opening a PR? Excellent! Please read the short CONTRIBUTING.md guidelines before you dive in.