Your first step toward contributing to Manifold should be to setup a development environment. Manifold requires a number of services for it to run correctly, so getting setup will require a little bit of work.
Step 1: Install dependencies
Install Homebrew and XCode command line tools
Homebrew is by far the easiest way to get the underlying dependencies in place for Manifold. Follow the instructions on the Homebrew Website to install Homebrew. As of January 2020, the command to install Homebrew is:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Update your PATH variable
Manifold relies on a number of binstubs. To simplify development, ensure that
./node_modules/.bin are both in your $PATH.
On MacOS 10.15 (Catalina) the default terminal shell was changed form bash to zsh. Zsh and bash are similar, but are not interchangable. If you don’t already know which shell you are using, this next command will tell you.
$0 responded with “zsh” then we are going to save our zsh configuration file to a variable called “profile”
$0 responded with “bash”, then we are going to save our bash configuration file to a variable called “profile”
Now we will modify our path using that profile variable we created earlier
touch $profile echo 'export PATH=./bin:$PATH' >> $profile echo 'export PATH=./node_modules/.bin:$PATH' >> $profile source $profile
Install rbenv and Ruby
Rbenv is a tool for managing the available Ruby versions on your computer. If you prefer .rvm or another mechanism for managing ruby versions, by all means use it, as long as you can get the correct version of Ruby installed.
As of January 2020, Manifold runs on Ruby 2.6.3. The version changes relatively frequently, as new versions of Ruby are released. We store the current required ruby version in a
.ruby-version file in the project root. Manifold should work with version 2.6 or higher.
First, install rbenv.
brew install rbenv
Second, adjust your profile so that rbenv is initialized when you open a new terminal session. Follow the directions given from running:
Third, install Ruby.
source $profile rbenv install 2.6.3
Install nodenv, Node, and yarn
We prefer nodenv for running different versions of Node. If you have a preferred means of installing node, go for it.
As of January 2020, Manifold runs on Node 12.14.0. The version changes relatively frequently, as new versions of Node are released. We store the current required node version in a
.node-version file in the project root.
First, install nodenv.
brew install nodenv
Second, adjust your profile so that nodenv is initialized when you open a new terminal session. Follow the directions given from running:
Third, install Node.
nodenv install 12.14.0
Fourth, install Yarn.
source $profile brew install yarn
Manifold stores most data in a PotsgreSQL database.
As of January 2020, our Manifold packages include Postgres 12.1. This version changes periodically. The current minimum version is recorded in our Omnibus packaging repository.
First, install PostgreSQL.
brew install postgres
Second, use Homebrew Services to run PostgreSQL in the background.
brew services start postgresql
Redis is an open source (BSD licensed), in-memory data structure store, used primarily by Manifold as a cache and message broker. Manifold is compatible with Redis v3, v4 and v5.
First, install Redis.
brew install redis
Second, use Homebrew Services to run Redis in the background.
brew services start redis
Ensure Java is present
Java is needed for ElasticSearch. We’ll use Homebrew Cask to install it. You will likely be prompted for your password.
brew tap homebrew/cask-versions brew cask install java
Install additional libraries
Manifold uses Imagemagick (or Graphicsmagick) for resizing images. It uses Pandoc for Word document ingestion.
brew install imagemagick pandoc
Step 2: Clone Manifold source
At Cast Iron, we typically store our projects in a
~/src directory. For the purposes of these instructions, we’ll assume you’re doing the same.
First, make a directory at
/Users/yourUserName/src and enter it.
mkdir -p ~/src cd ~/src
Second, clone the Manifold source code with git and enter the source directory.
git clone https://github.com/ManifoldScholar/manifold.git manifold cd ~/src/manifold
Step 3: Install API dependencies and setup the database.
Next, install Bundler and Manifold’s gem dependencies. There is a Gemfile in the root of the repository, which includes dependencies related to Manifold’s tooling. There is also a Gemfile in the
api directory, which is the root of the Rails application that is Manifold’s API backend. You’ll need to install both sets of gems.
cd ~/src/manifold gem install bundler bundle install cd ~/src/manifold/api bundle install
Step 4: Setup .env file.
Generate a secret key and store it. You’ll add it to the environment file below, where it says
cd ~/src/manifold/api rails secret
Copy that key to your clipboard. Create a file at
~/src/manifold/.env with the following contents:
DOMAIN=localhost API_PORT=3020 API_CABLE_PORT=3021 CLIENT_SERVER_PORT=3010 CLIENT_URL=http://localhost:3010 CLIENT_BROWSER_API_URL=http://localhost:3020 CLIENT_BROWSER_API_CABLE_URL=ws://localhost:3021/cable CLIENT_SERVER_API_URL=http://localhost:3020 CLIENT_SERVER_PROXIES=true NODE_ENV=development RAILS_ENV=development RAILS_SECRET_KEY=ENTER_YOUR_SECRET_KEY RAILS_DB_NAME=manifold_development ELASTICSEARCH_URL=http://127.0.0.1:29200
Step 5: Create the database.
The API is a Rails application, and you’ll use standard Rails commands to manage the database. The following commands create the database, loads the schema, and add seed data.
cd ~/src/manifold/api rails db:create rails db:schema:load rails db:seed
While you’re at it, go ahead and create an admin user. Be sure to replace the values in the command below with your email, password, first name, and last name.
Step 6: Install client dependencies
client directory, which contains Manifold’s client application.
cd ~/src/manifold/client yarn install
Step 7: Install ElasticSearch
Manifold includes a command line tool that helps with some development tasks at
bin/manifold. You can use this tool to install ElasticSearch in the top level
services folder. As of January 2020, Manifold uses ElasticSearch version 7.5.1.
cd ~/src/manifold manifold install elasticsearch
Step 8: Start Manifold
The first time you start Manifold, it will be a little bit slower than usual. Start all services with the
manifold start command.
cd ~/src/manifold manifold start
Step 9: Open Manifold in your browser
Open a web browser and go to http://localhost:3010. If all went according to plan, you can now interact with the instance of Manifold running locally. You should now be able to login to the backend with the user you setup earlier.
You did it!
You should now have a functioning Manifold development environment. We use Webpack for the client application, and changing most files in the client directory will cause assets to be rebuild. We also have hot module reloading in place for the client application, so any changes you make to a component will cause the component to be re-rendered in your browser.
Check back soon for our contribution guidelines. In the meantime, if you’d like to contribute code to Manifold, please do so in the form of a pull request to the upstream repository.