Developing Locally
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.
These instructions may be a little bit out-of-date, and your mileage may vary. We're hoping to circle back soon to update, and would love a pull request to our documentation with improvements to this page.
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 ./bin and ./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.
echo $0
If $0 responded with "zsh" then we are going to save our zsh configuration file to a variable called "profile"
profile=~/.zshrc
If $0 responded with "bash", then we are going to save our bash configuration file to a variable called "profile"
profile=~/.bash_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:
rbenv init
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.
The Manifold development team uses Yarn rather than NPM to manage javascript dependencies.
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:
nodenv init
Third, install Node.
nodenv install 12.14.0
Fourth, install Yarn.
source $profile
brew install yarn
Install Postgres
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
Install Redis
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 ENTER_YOUR_SECRET_KEY
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.
rails manifold:user:create:admin\["email@email.com","password","FirstName","LastName"\]
Step 6: Install client dependencies
Now it's time to install Manifold's javascript dependencies. There is a package.json file in the 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.