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.
caution
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:
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.
If $0 responded with "zsh" then we are going to save our zsh configuration file to a variable called "profile"
If $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
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.
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.
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.
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.
Fourth, 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.
Second, use Homebrew Services to run PostgreSQL in the background.
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.
Second, use Homebrew Services to run Redis in the background.
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.
Install additional libraries#
Manifold uses Imagemagick (or Graphicsmagick) for resizing images. It uses Pandoc for Word document ingestion.
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.
Second, clone the Manifold source code with git and enter the source directory.
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.
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
Copy that key to your clipboard. Create a file at ~/src/manifold/.env with the following contents:
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.
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#
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.
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.
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.
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.