You'll need Ruby to install the Zendesk App Tools (ZAT). ZAT is a Ruby gem -- a self-contained package of Ruby code that extends Ruby. You don't need to know Ruby to use the tools but you do need Ruby to install the gem.

Both macOS and Ubuntu in Windows 10 already have a version of Ruby installed. You'll need Ruby 2.1 or later to install the ZAT gem.

To find out what version you have, run the following command in your Bash shell:

$ ruby -v

The output should show your version of Ruby. If necessary, update the version to 2.1 or later as described in the rest of this article.

This article describes how to install and manage different versions of Ruby on your system with a tool called rbenv (for Ruby environment). rbenv lets you install versions of Ruby side-by-side and specify which one to use on a per-project basis or globally. This is very useful if you need to work with a particular Ruby version.

Topics covered in this article:

The other articles in the series cover the following topics:

Disclaimer: Zendesk can't provide support for third-party technologies such as Ruby. Post any issues in the comments section or search for solutions online.

Installing rbenv in Ubuntu

This section assumes you enabled the Windows Linux Subsystem and installed Ubuntu from the Microsoft Store. For instructions, see Setting up a Bash shell in Windows 10 in the first article of this series.

The package manager in Ubuntu is apt-get. It retrieves and installs applications, libraries, and dependencies automatically.

To install rbenv in Ubuntu in Windows

  1. In PowerShell or at the Windows command prompt, run bash to start the Bash shell.
  2. Run the following housecleaning command:

    $ sudo apt-get update
    Note: Some Windows 10 users have shared that the following command is necessary for this to work:
    $ sudo apt-get install ruby-all-dev

    sudo stands for "superuser do". It lets you run commands as administrator. When prompted for a password, use the Unix password you set when installing Ubuntu, not your Windows password.

    It's best-practice to run apt-get update before installing new packages. It retrieves information from various servers to keep the index of packages (not the packages themselves) on your system up-to-date with their sources. If you don’t update the index, the system won’t know that newer packages exist. To update the packages themselves, you'd run apt-get upgrade after this command.

  3. Run the following command to upgrade or install required dependencies to build Ruby from source:

    $ sudo apt-get install -y build-essential curl git libreadline-dev libssl-dev zlib1g-dev

    The command installs or upgrades a number of associated packages. It may take a few minutes.

    Some packages, such as curl and git, are installed with Ubuntu, but including them in apt-get install upgrades them to the latest version. To get the upgrades, make sure you run apt-get update in step 2 first.

    The -y option provides an automatic yes to all prompts during installation.

  4. Install rbenv:

    $ sudo apt-get install rbenv
  5. Add rbenv to your system's $PATH variable:

    $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
    $ echo 'eval "$(rbenv init -)"' >> ~/.bashrc

    The commands append the strings in single quotes to your system's .bashrc file.

    Caution: Never attempt to edit Linux system files like .bashrc with a Windows text editor. Windows file metadata differs from Linux file metadata. You could corrupt or damage your Linux environment. Use Bash commands as above, or use a Linux text editor such as nano or vi. You can also use a specialized Windows editor like Notepad++ that can save text as Unix script files.

    Fortunately, the reverse is not true. You can use Linux tools to work with files in the Windows file system. For example, you can edit a file in the C drive with the following Bash command: mnt/c/apps/zendesk/my_app$ nano manifest.json.

    For maximum flexibility, put all your dev projects in the Windows file system. You can use both Windows and Linux tools to work on them.

  6. Reload your shell:

    $ source ~/.bashrc
  7. Install a rbenv plugin called ruby-build by cloning it from Github:

    $ mkdir -p "$(rbenv root)"/plugins$ git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

    ruby-build builds versions of Ruby from source.

  8. Verify rbenv is configured properly:

    $ type rbenv

    The output should say that rbenv is a function.

You can now install and use different versions of Ruby on your system. See Installing and using different Ruby versions below.

Installing rbenv in macOS

You can use the Homebrew package manager to install rbenv in macOS. See Installing Homebrew in the first article of this series.

To install rbenv in macOS

  1. In Terminal, enter the following commands, waiting for each process to finish before entering the next line:

    $ brew update
    $ brew install rbenv ruby-build rbenv-default-gems rbenv-gemset
    $ echo 'eval "$(rbenv init -)"' >> ~/.bashrc
    $ source ~/.bashrc
  2. Verify that rbenv is configured properly:

    $ type rbenv

    The output should say that rbenv is a function.

You can now install and use different versions of Ruby on your system.

Installing and using different Ruby versions

After installing rbenv, you can use it to install versions of Ruby side-by-side and then switch between versions.

To install a version of Ruby

  1. List the versions you can install:

    $ rbenv install --list

    You can only install versions on the list.

  2. Install a version:

    $ rbenv install <version>

    where <version> is a string from the list.

    Example:

    $ rbenv install 2.6.4

    Note: It can take a long time, particularly in Windows Ubuntu, to build and install a version from source. Please be patient.

To use a version for a specific project

  • Run the following command in the project folder:

    $ rbenv local <version>

    where <version> is an installed version.

    Example:

    $ cd ~/projects/my_older_project$ rbenv local 2.0.0-p353

    Tip: To list the installed versions you can choose, run rbenv versions.

To use a version as the default version on your system

  • Run:

    $ rbenv global <version>

    where <version> is an installed version.

    Example:

    $ rbenv global 2.6.4

To list the versions installed on your system

$ rbenv versions

To list the working version

$ rbenv version

Installing Ruby gems

A gem is a Ruby package. Use the gem install command to install a gem, as follows:

$ gem install <gem-name>

Before you start installing gems, however, install Bundler, a gem manager that is itself a gem. Bundler manages an application's dependencies, which are like a shopping list of other libraries that the application needs.

To install Bundler

  1. Restart your Bash shell.

    In macOS, quit and reopen Terminal or run source ~/.bash_profile.

    In Ubuntu, run source ~/.bashrc.

  2. Install Bundler:

    $ gem install bundler
  3. Install the Zendesk Apps Tools gem:

    $ gem install zendesk_apps_tools
  4. View available ZAT commands:

    $ zat h

    You should see the following output:

    Commands:  zat clean            # Remove app packages in temp folder  zat create           # Create and install app on your account  zat help [COMMAND]   # Describe available commands or one specific command  zat new              # Generate a new app  zat package          # Package your app  zat server           # Run a http server to serve the local app  zat theme SUBCOMMAND # Development tools for Theming Center (Beta)  zat update           # Update app on the server  zat validate         # Validate your app  zat version, -v      # Print the version

    Note: You don't need sudo to install gems.

See rubygems.org for more gems.

If you only want to install a gem in a specific version of Ruby, use rbenv to change to the version first. Example:

$ rbenv local 2.0.0-p353$ gem install double_doc

You now have the basics to begin getting started with apps.

When you're ready, continue to System prep for app developers 3: Installing Node.js.