Skip to content

Local Installation and Management of dependencies

Jump to bottom
Martha Thompson edited this page Mar 28, 2022 · 14 revisions

USE THIS DOCUMENT AT YOUR OWN RISK! This document is likely to contain outdated information. As mentioned in the README, we recommend using Docker for installing and running dependencies. The instructions below are based on our older workflow, requiring local installation of each package and service.

Ruby

We recommend using RVM to install and manage local Rubies. You will need the version of Ruby specified in .ruby-version. Verify that your path points to the correct version of Ruby:

$ ruby -v

You should see output similar to the following:

ruby 2.5.5p157 (2019-03-15 revision 67260) [x86_64-darwin18]

Homebrew

We recommend using Homebrew for local package installation on a Mac.

Packages

The cld3 gem, which we use for language detection, depends on Google's protocol buffers and a C++ compiler:

brew install gcc
brew install protobuf

Gems

For Rails 5, we use bundler; you should be able to get all the rest of the gems needed for this project like this:

gem install bundler
bundle install

Database

Install MySQL 5.7.x using Homebrew:

$ brew update
$ brew search mysql

The output should include [email protected] listed under Formulae.

$ brew install [email protected]

Follow the instructions provided by Homebrew during installation.

Start or restart MySQL:

$ brew services start [email protected]

You may need to reinstall the mysql2 gem if you changed your MySQL version:

gem uninstall mysql2
bundle install

Refer to Gem Installation gotchas and solutions for tips on installing the mysql2 gem.

Create and setup your development and test databases. The database.yml file assumes you have a local MySQL database server up and running, accessible from user 'root' with no password.

$ rails db:setup
$ rails db:test:prepare

Troubleshooting your database setup

Problems may arise if you have multiple versions of MySQL installed, or if you have installed MySQL via the OSX installer instead of or in addition to Homebrew. Below are some troubleshooting steps:

Verify that you are running the Homebrew-installed version of MySQL (as indicated by the /usr/local/opt/[email protected] directory):

$ ps -ef | grep mysql
  502 26965     1   0 12:23PM ??         0:00.04 /bin/sh /usr/local/opt/[email protected]/bin/mysqld_safe --bind-address=127.0.0.1 --datadir=/usr/local/var/mysql

Verify that Rails is using the Homebrew version:

$ rails db

The output should include:

Server version: 5.6.<x> Homebrew

Elasticsearch

We're using Elastic 6.8 for fulltext search and query analytics.

$ brew search elasticsearch
$ brew install [email protected]
$ brew services start [email protected]

To check settings and directory locations:

$ curl "localhost:9200/_nodes/settings?pretty=true"

Elasticsearch uses port 9200 by default. You will need to update config/secrets.yml to specify port 9200 instead of 9268 for the custom indices and analytics.

To change the defaults, like number of shards/replicas, edit this file:

$ sudo vi /usr/local/Cellar/elasticsearch/6.8.8/libexec/config/elasticsearch.yml

index.number_of_shards: 1
index.number_of_replicas: 0

The default JVM heap is 256m with a max of 1g. You can increase it by editing your ~/Library/LaunchAgents/homebrew.mxcl.elasticsearch.plist file like this:

<dict>
  <key>ES_JAVA_OPTS</key>
  <string>-Xss200000</string>
  <key>ES_HEAP_SIZE</key>
  <string>4g</string>
  <key>ES_MAX_MEM</key>
  <string>4g</string>
</dict>

Now restart it:

$ launchctl unload ~/Library/LaunchAgents/homebrew.mxcl.elasticsearch17.plist
$ launchctl load ~/Library/LaunchAgents/homebrew.mxcl.elasticsearch17.plist

If you aren't using Homebrew to install and configure Elasticsearch, follow the instructions to download and run it.

Redis

We're using the Redis key-value store for caching, queue workflow via Resque, and some analytics. Download and install the Redis server:

$ brew install redis

Verify that redis-server is in your path

$ which redis-server
/opt/redis/bin/redis-server

Imagemagick

We use Imagemagick to identify some image properties. It can also be installed with Homebrew on a Mac.

$ brew install imagemagick

Asynchronous tasks

Several long-running tasks have been moved to the background for processing via Resque. Here is how to see this in action on your local machine, assuming you have installed the Redis server.

  1. Run the redis-server

    % redis-server

  2. In your admin center, create a SAYT suggestion "delete me". Now create a SAYT filter on the word "delete":

    http://localhost:3000/admin/

  3. Look in the Resque web queue to see the job enqueued.

  4. Start a Resque worker to run the job:

    % QUEUE=* rake environment resque:work

At this point, you should see the queue empty in Resque web, and the suggestion "delete me" should be gone from the sayt_suggestions table.

Clone this wiki locally