tokaido mac
Last updated 28 February 2014
Installing Ruby on Rails 3.2.13 using Tokaido, a Mac OS X application.
Detailed instructions for getting started on Tokaido with Rails including advice to get you fully productive.
Tokaido is currently available in prerelease. That means you may encounter issues, which you can review and report on GitHub.
For example, this issue is currently unresolved: Can’t Update from Rails 3.2.13 to Rails 4.0 at the time this was written.
Tokaido is a Mac OS X application you can download and install almost as easily as any other Mac application. Launching the application gives you a fully configured Ruby on Rails development environment. You’ll still use the Terminal application for many Rails commands, and you’ll use a text editor to write code. But Tokaido gives you a point-and-click interface for launching the application and monitoring the development logs.
The goal of the Tokaido project is described in an April 2012 blog post by Yehuda Katz, Tokaido: My Hopes and Dreams, and progress is documented on the Kickstarter Tokaido campaign pages.
Tokaido is a free, open source application developed by Yehuda Katz and a team of volunteers.
If you’re new to Rails, see What is Ruby on Rails?, the book Learn Ruby on Rails, and recommendations for a Rails tutorial.
This is an article from the RailsApps project. The RailsApps project provides example applications that developers use as starter apps. Hundreds of developers use the apps, report problems as they arise, and propose solutions. Rails changes frequently; each application is known to work and serves as your personal “reference implementation” so you can stay up to date. Each is accompanied by a tutorial so there is no mystery code. Support for the project, including the example applications and the Rails Composer tool, comes from subscribers to the RailsApps tutorials.
Before Tokaido was available, installation of Ruby on Rails on Mac OS X was challenging for beginners. Tokaido makes installing Rails almost as easy as installing any other Mac OS X application. You’ll still need to install the Apple Xcode Command Line Tools to update Rails and install other gems, and you’ll need to install other development tools such as Git, but installing Tokaido itself is simple.
Tokaido installs a working copy of Ruby, Rails, and all necessary gems into the user’s system, set up for use from the Mac OS X Terminal application. After you install Apple’s Xcode Command Line Tools and Git, you’ll have a fully functional development environment.
The development environment is “sandboxed,” which means it has minimal dependencies on your Mac system software and is isolated so that installing Tokaido does not change the configuration of your Mac system software. You can build Rails applications in the Tokaido sandbox, knowing they will run within the Tokaido application without dependencies or interaction with the Mac system software.
With Tokaido, you build Rails applications with a text editor and Terminal application. The Terminal is launched through the Tokaido application, setting up the $PATH, $GEM_HOME and the rest of the required environment, reducing common failure scenarios that make Ruby hard to install or that emerge over time through environment changes or OS upgrades.
Tokaido is not the development environment used by most professional Rails developers. Most Rails developers use Mac OS X or Ubuntu Linux with a custom installation of Ruby and Rails from the command line, using RVM, Chruby, or rbenv to manage Ruby versions. Installation of Ruby on Rails using RVM is not particularly difficult and it is well documented. If you intend to become a full-time Rails developer, it is advisable to gain experience installing Ruby on Rails using RVM to understand its relationship with the Mac OS X or Ubuntu Linux system environment. Here are instructions:
Install Ruby on Rails on Mac OS X
Installation of Ruby on Rails on your laptop or desktop workstation has an additional drawback. You will be dependent on the physical presence of the computer that stores all your files and contains your Rails development environment. If the computer crashes or is stolen, you’ll be unproductive until you replace and restore your computer. Likewise, if you frequently work on more than one computer, you’ll be hobbled by the difficulty of maintaining duplicate development environments. For these reasons some developers prefer to “work in the cloud” using a hosted development environment such as Nitrous.io. For more on Nitrous.io, see the article:
Tokaido does not always contain the most recent and up-to-date versions of Ruby or Rails. For example, the first prerelease version shipped with ruby 2.0.0p195; Ruby 2.0.0p353 was the most recent version of Ruby when this was written. This is a minor inconvenience and not important to most Rails beginners.
Similarly, Rails 4.0 was released June 25, 2013 but the Tokaido prerelease version of July 16, 2013 shipped with Rails 3.2.13.
At the present time (the first prerelease version), Tokaido doesn’t support RVM so it is not possible to use RVM to manage Ruby versions or create and manage gemsets.
In summary, Tokaido is suitable for a casual or hobbyist Rails developer. Given that you must install a C language compiler and Git before using Tokaido, and that installing Ruby on Rails using RVM is not particularly difficult, Tokaido may not have much advantage over installing Ruby on Rails using RVM, unless you have encountered problems installing Ruby on Rails using RVM on your Mac.
Before installing Tokaido, install the Xcode Command Line Tools and Git.
You will need a C language compiler to add updated versions of Ruby or Rails. Also, many gems use native extensions and require a C language compiler for installation.
It is best to install Apple’s Xcode Command Line Tools to get a C language compiler. See the article:
for complete instructions.
Git provides a source control repository. Developers use Git to roll back code changes as needed, to collaborate with others, and deploy applications for hosting with a service such as Heroku. As a Rails developer, you’ll use Git with a GitHub account for remote backup and collaboration.
See the article Rails with Git and GitHub for more information.
If you are building a throw-away app for your own education you may decide not to use Git immediately, but sooner or later you will need to use Git in Rails development.
The easiest way to install Git is with GitHub for Mac.
Before you download GitHub for Mac, get a free GitHub account. When you register, use your real name. Your GitHub account is as important as a résumé or a business card so use the name by which you are known professionally.
Download the GitHub for Mac application. Drag the application into your Applications folder. Launch the GitHub application to begin installation. You’ll be asked for your GitHub account username and password. The GitHub application will generate and install a public key. The public key is used to encrypt connections between your computer and GitHub. You’ll get an email message from GitHub informing you that a new public key was added to your GitHub account.
In the GitHub application, you’ll see this screen next:
Before continuing, click the button to “Install Command Line Tools.”
The application will install the Git executable into the hidden /usr/local/bin/ system folder. You’ll be prompted for your Mac login password to make the addition to your system files (the button is labeled “Install Helper”). The application will inform you that installation is complete. Clicking “Continue” will give you an option to identify local repositories (folders on your laptop that you want to back up to GitHub). Skip this step and select “Done.” You’ll see the GitHub for Mac main window.
You can quit GitHub for Mac. It is a graphical front-end for Git that you can use to become familiar with Git. Very few Rails developers use the GitHub for Mac application; since you will be using the Terminal to build Rails applications, it is easier to use Git from the command line. Installing GitHub for Mac is just the easiest way to install the Git executable.
Visit the Tokaido Releases page on GitHub.
At the very bottom of the page, click the green button labeled “Tokaido.zip” to download the app.
In your downloads folder, double-click the Tokaido.zip file to unarchive the app.
Drag the Tokaido application to your Applications folder.
Drag the Tokaido application from your Applications folder to your Dock if you expect to use it regularly.
When you click the application to open it, you may see a warning that Tokaido can’t be opened because it is from an unidentified developer. Try launching the application again but this time, right click on the application icon. You can right click on a Mac by pressing the Control key when you click. Select “Open” from the menu.
When you click to launch the application for the first time, you’ll see a message that “Tokaido is trying to install a new helper tool.” You must enter your Mac login password to continue. Click “Install Helper.”
Click Tokaido again to launch it.
In the prerelease version, the user interface is very sparse. You’ll see an empty window titled “Tokaido” with a single button, “Open in Terminal.”
Click the button, “Open in Terminal,” to launch the Mac OS X Terminal application.
You’ll see a window for the Terminal application. You’ll be using it a lot, so stretch the window vertically to the full height of your display.
You can launch the Terminal application, or console, from Tokaido. Or you can launch it from the Mac Finder. Here’s the difference. When you launch it from Tokaido, a recent version of Ruby is available and Rails is pre-installed. When you launch it from the Finder, the Mac’s older system Ruby is on tap and Rails is not installed.
Let’s use the command line to explore Tokaido and create a Rails application.
We call the command line the shell because it is the outer layer of the operating system’s internal mechanisms (which we call the kernel).
If you haven’t used the computer’s command line interface (CLI) before, spend some time with The Command Line Crash Course to become comfortable with Unix shell commands.
Try out the terminal application by entering a shell command.
$ whoami
Don’t type the $ character. The $ character is a cue that you should enter a shell command. This is a longtime convention that indicates you should enter a command in the terminal application or console.
The Unix shell command whoami returns your username.
Don’t type the $ prompt.
You might see:
-bash: $: command not found
which indicates you typed the $ character by mistake.
Use the Unix ls -1pa command to list the contents of your home folder:
$ ls -1pa ./ ../ .DS_Store .Trash/ .bash_history .ssh/ .swt/ .tokaido/ Desktop/ Documents/ Downloads/ Library/ Movies/ Music/ Pictures/ Public/
It’s likely you’ll have many more files and folders than the few you see above.
Somewhere in the list you’ll see:
.tokaido
It’s a hidden folder (the filename begins with a dot) so you can’t see it in the Finder file browser.
You can open it, however, if you wish to examine the folder:
$ open .tokaido
The .tokaido folder contains everything needed for a complete Ruby on Rails development environment, including a recent version of Ruby and several folders containing gems, including the gems required for Rails.
It’s not a good idea to directly manipulate any files inside the hidden .tokaido folder. If you do, you should delete and reinstall Tokaido.
You won’t create anything inside the hidden .tokaido folder. But you’ll need a convenient folder to store your Rails projects. You can give it any name, such as code/ or projects/. For this tutorial, we’ll call it workspace/.
Create a projects folder and move into the folder:
$ mkdir workspace $ cd workspace
This is where you’ll create your Rails applications.
If you wish, Tokaido gives you everything you need to immediately create a Rails application.
However, before you create your first Rails application, it’s worthwhile to take time to get acquainted with the Rails development environment.
A recent version of Ruby is pre-installed:
$ ruby -v ruby 2.0.0p195 (2013-05-14 revision 40731) [x86_64-darwin12.3.0]
You can check for the current recommended version of Ruby. It’s not easy to install a newer version of Ruby so it is best to wait for a Tokaido update.
A recent version of Rails is pre-installed:
$ rails -v Rails 3.2.13
Check for the current version of Rails.
It’s best to update to the newest version of Rails.
NOTE: At this time, it’s not possible to update to a new version of Rails. Fails with error: “Could not create Makefile due to some reason, probably lack of necessary libraries and/or headers.” See issue 33.
If you want the most recent stable release:
$ gem update rails
If you want the newest beta version or release candidate, you can install with --pre.
$ gem install rails --pre $ rails -v
Or you can get a specific version.
For example, if you want the Rails 3.2.16 release:
$ gem install rails --version=3.2.16 $ rails -v
If you want to learn about the differences between Rails versions, see a Ruby on Rails Release History.
RubyGems is the gem manager in Ruby.
Check the installed gem manager version:
$ gem -v 2.1.5
You should have:
- RubyGems 2.1.5 — check for newer version
Use gem update --system to upgrade the Ruby gem manager if necessary.
You can see a list of all the gems that are pre-installed with Tokaido:
$ gem list ### list not shown for brevity
You can see the location in the file system where these gems are stored:
$ gem which rails /Users/yourname/.tokaido/Gems/gems/railties-3.2.13/lib/rails.rb
You’ll never directly move or remove the gem files but it is helpful to know that they are being managed by Tokaido.
A trouble-free development environment requires the newest versions of the Tokaido gems.
Several gems are installed with Ruby:
- bigdecimal (1.2.0) check for newer version
- bundler (1.3.5) check for newer version
- bundler-unload (1.0.1) check for newer version
- io-console (0.4.2) check for newer version
- json (1.8.0) check for newer version
- minitest (5.0.6) check for newer version
- psych (2.0.0) check for newer version
- rake (10.1.0) check for newer version
- rdoc (4.0.1) check for newer version
- test-unit (2.5.5) check for newer version
Others are part of the Tokaido installation of Rails.
To get a list of gems that are outdated:
$ gem outdated ### list not shown for brevity
To update all stale gems:
$ gem update ### list not shown for brevity
You can stay informed of new gem versions by creating an account at RubyGems.org and visiting your dashboard. Search for each gem you use and “subscribe” to see a feed of updates in the dashboard (an RSS feed is available from the dashboard).
After you’ve built an application and set up a GitHub repository, you can stay informed with Gemnasium or VersionEye. These services survey your GitHub repo and send email notifications when gem versions change. Gemnasium and VersionEye are free for public repositories with a premium plan for private repositories.
You may see this error when installing a gem:
. . . Could not create Makefile due to some reason, probably lack of necessary libraries and/or headers. Check the mkmf.log file for more details. You may need configuration options. . . . The compiler failed to generate an executable file. (RuntimeError) You have to install development tools first. . . .
The error indicates you did not install a C language compiler using the OSX GCC Installer or Apple’s Xcode Command Line Tools.
To create a new Rails application, first make sure you are in the workspace/ folder:
$ pwd /Users/yourname/workspace
Then use the rails new command:
$ rails new myapp
Change into the project root directory:
$ cd myapp
For a “smoke test” to see if everything runs, display a list of Rake tasks.
$ rake -T
You can launch your Rails application from the command line:
$ rails server
Open a browser window and navigate to http://localhost:3000/ to see the application. You’ll see the default Rails welcome page.
Stop the server with Control-c.
Tokaido gives you another way to launch a Rails application, which we’ll consider below.
The starter application you create with rails new is very basic.
Use the Rails Composer tool to build a full-featured Rails starter app.
You’ll get a choice of starter applications with basic features and popular gems.
Here’s how to generate a new Rails application using the Rails Composer tool:
Using the conventional approach:
$ rails new myapp -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb
You can add the -T flags to skip Test::Unit if you are using RSpec for testing.
You can add the -O flags to skip Active Record if you are using a NoSQL datastore such as MongoDB.
The RailsApps project provides example apps that show how real-world Rails applications are built. Each example is known to work and can serve as your personal “reference implementation”. Each is an open source project. Dozens of developers use the apps, report problems as they arise, and propose solutions as GitHub issues. There is a tutorial for each one so there is no mystery code. Purchasing a subscription for the tutorials gives the project financial support.
| Example Applications for Rails 4.2 | Tutorial | Comments |
|---|---|---|
| Learn Rails | Learn Ruby on Rails | introduction to Rails for beginners |
| Rails and Bootstrap | Rails Bootstrap Tutorial | starter app for Rails and Bootstrap |
| Rails and Foundation | Rails Foundation Tutorial | starter app for Rails and Zurb Foundation |
| Mailing List with Active Job | Mailing List with Active Job Tutorial | background processing |
| OmniAuth and Rails | OmniAuth Tutorial | OmniAuth for authentication |
| Devise and Rails | Devise Tutorial | Devise for authentication |
| Role-Based Authorization | Role-Based Authorization Tutorial | Simple authorization |
| Pundit and Rails | Rails Pundit Tutorial | Pundit for authorization |
| Sign Up and Download | Sign Up and Download Tutorial | Devise with authorization to download a PDF file |
| Stripe Checkout | Stripe Checkout Tutorial | selling a product with Stripe Checkout |
Earlier we saw how to launch a Rails application from the command line.
Tokaido gives you the option of managing your application from within Tokaido.
In the Tokaido main window, click the “plus” icon to add a new application. You must already have built a new application from the command line or downloaded a project for elsewhere (from GitHub, for example). Find the folder in the file browser and click “Open” to manage it with Tokaido.
Tokaido will display an icon for the application.
A new button, “Boot App,” will be available. Clicking “Boot App” launches the Rails server, the same thing as entering rails server in the console. Open a browser window and navigate to http://localhost:3000/ or http://myapp.tokaido/ to see the application. Stop the server by clicking the “Shut Down” button in the Tokaido main window.
Below the app icon in the Tokaido main window, you’ll find a drop-down menu with several choices:
- Activate or Deactivate – same as “Boot App” or “Shut Down”
- Activate on Launch – run the app as soon as you launch Tokaido
- Show Logs – open a console window that displays the diagnostic server logs
- Show in Finder – open the Finder file browser
- Open in Browser – Open a browser to http://myapp.tokaido/
- Edit – change the icon image or application name
- Remove – delete from Tokaido (but not from your file system)
Tokaido gives you a point-and-click interface for managing your application. You still have to use a text editor to edit your application code. And for many Rails commands, you’ll still use the Terminal. But launching the application and monitoring the logs can be managed from the Tokaido main window.
You’ve already installed Git using the GitHub for Mac application.
Check that Git is configured correctly:
$ git config -l --global . . . user.name=Real Name [email protected]
If Git is installed on your computer and you’ve used a RailsApps application template to create your starter app, you’ll already have a Git repository.
Rails uses the SQLite database by default. Mac OS X comes with SQLite pre-installed and there’s nothing to configure.
Though SQLite is adequate for development (and even some production applications), a new Rails application can be configured for other databases. The command rails new myapp --database= will show you a list of supported databases.
Supported for preconfiguration are: mysql, oracle, postgresql, sqlite3, frontbase, ibm_db, sqlserver, jdbcmysql, jdbcsqlite3, jdbcpostgresql, jdbc.
To create a new Rails application to use PostgreSQL:
$ rails new myapp --database=postgresql
The --database=postgresql parameter will add the pg database adapter gem to the Gemfile and create a suitable config/database.yml file.
Don’t use the --database= argument with the Rails Composer tool. You’ll select a database from a menu instead.
Tokaido easily interfaces with a PostgreSQL database if you use the easy-to-install Max OS X Postgres.app.
If you have Postgres.app installed, “Open in Terminal” will detect it and make the Postgres binaries and libraries available to the Terminal. This works by modifying environment variables at boot, so if you boot Postgres.app after opening the Terminal, you will need to reopen the Terminal.
Redis is a fast key-value datastore that keeps data in memory and uses disk storage only for persistence. It is popular for caches and simple look-up tables in Rails. It is seldom used by beginners but professional developers often use it as a fast complement to SQL databases.
Tokaido includes everything needed to use Redis. You can open the Terminal and run redis-server to launch the Redis server.
If you wish to run your own servers, you can deploy a Rails application using Capistrano deployment scripts. However, unless system administration is a personal passion, it is much easier to deploy your application with a “platform as a service” provider such as Heroku.
For easy deployment, use a “platform as a service” provider such as:
For deployment on Heroku, see the article:
By design, Rails encourages practices that avoid common web application vulnerabilities. The Rails security team actively investigates and patches vulnerabilities. If you use the most current version of Rails, you will be protected from known vulnerabilities. See the Ruby On Rails Security Guide for an overview of potential issues and watch the Ruby on Rails Security Mailing List for announcements and discussion.
Rails uses a session store to provide persistence between page requests. The default session store uses cookies. To prevent decoding of cookie data and hijacking a session, Rails encypts cookie data using a secret key. When you create a new Rails application using the rails new command, a unique secret key is generated and written to the config/initializers/secret_token.rb file. If you’ve generated a Rails application and committed it only to a private GitHub repository, you do not need to change the secret key. However, if you’ve cloned a public GitHub repository or made your application publicly available on GitHub, you must change the secret key when you deploy. The command rake secret generates a new random secret you can use. The command won’t install the key; you have to copy the key from the console output to the config/initializers/secret_token.rb file. Remember, you should never deploy an application to production that uses a publicly available secret token (obviously, it is not secret if it is public!).
Your best source for help with problems is Stack Overflow. Your issue may have been encountered and addressed by others.
Daniel Kehoe wrote the article.