Installation & Deployment

Configuring data stores

The Kochiku web server requires two data stores: MySQL (5.0 or later) and Redis (2.2 or later). Installation instructions for these data stores are available on their respective project websites. Kochiku worker machines do not require these data stores.

MySQL

After you install MySQL on the machine that will run the Kochiku web server:

1. Create a kochiku database and a kochiku MySQL user on the server machine.
2. On your own machine, copy the sample configuration file from config/database.production.yml.sample to config/database.production.yml and edit it to include your database's connection details.

When you deploy the Kochiku web server, config/database.production.yml is copied from your machine to the server machine at config/database.yml.

Redis

Kochiku uses Resque for its job system, which depends on Redis.

After you install Redis on the server machine, you don't need to configure it beyond ensuring that it's running on the default port (6379).

Javascript

Kochiku (like other Rails applications using the asset pipeline) uses execjs for the javascript requirements. By default, Kochiku will use the V8 interpreter embedded inside therubyracer gem. If you would like to use a different Javascript runtime you can override the default with the EXECJS_RUNTIME environment variable.

Installing the web server

Kochiku is a Ruby on Rails project. Although you can run it locally using rails server, you will typically be deploying with Capistrano. Configuration information is specified in kochiku/config/application.yml. You need to maintain changes to this file on your Kochiku server. You can do this with any of the following methods:

• Put application.yml in Capistrano's shared directory and create a symlink to it from current.
• Fork Kochiku to your private git server and commit your modifications to application.yml.

Before you deploy the web server, edit kochiku/config/application.yml to set the host value for kochiku_host to point to your server machine.

If you need to customize the deploy, edit kochiku/config/deploy/production.rb to specify additional Capistrano tasks or override the existing tasks in kochiku/config/deploy.rb.

Basic web server deployment steps

git clone https://github.com/square/kochiku.git
cd kochiku
gem install bundler
bundle install
# Edit config/application.yml
# Edit config/deploy/production.rb
cap production deploy

Web server configuration (recommended)

In order to view gzipped artifacts (e.g. log files) in the browser (as opposed to having them be downloads), make sure that you web server sets the Content-Encoding header. For example, for nginx, add the following to your nginx config file:

location ~* log_files.*?\.gz {
    types { text/plain gz; }
    add_header Content-Encoding gzip;
}

Configuring the github access token

In order to use the Github integration you will need to generate an API access token for the github account. Place the API token in a file on your server and then set the path to that file in the git_servers section of config/application.yml.

git_servers:
  github.com:
    type: github
    oauth_token_file: /path/to/github_oauth_token

Installing workers

Note: The Kochiku worker implementation lives in a separate repository: square/kochiku-worker. You need to clone that repository in addition to the main Kochiku repository.

Like the web server, Kochiku workers are deployed with Capistrano. To deploy, you need to provide the following information in kochiku-worker/config/deploy_hosts.yml:

• The location of the Kochiku web server
• The location of the Kochiku Redis server
• The hostnames of all worker machines

When you deploy workers, the values in kochiku-worker/config/deploy_hosts.yml on your local machine are used to create a new config/kochiku-worker.yml file on each worker host.

If you need to customize the deploy, edit kochiku-worker/config/deploy/production.rb to specify additional Capistrano tasks or override the existing tasks in kochiku-worker/config/deploy.rb.

Basic worker deployment steps

git clone https://github.com/square/kochiku-worker.git
cd kochiku-worker
gem install bundler
bundle install
# Edit config/deploy_hosts.yml
# Edit config/deploy/production.rb
# Customize deployment further by adding cap tasks to lib/capistrano/tasks/
cap production deploy

Setting up log streaming

We have an additional, optional component to support real time tailing of logs. The logstreamer is written in go, and resides in the kochiku-worker repository. The logstreamer needs to be compiled and then transferred to each worker. Detailed instructions on setting up log streaming are found in the README for the logstreamer.