If you’d like to submit code to the BOP Digital Platform or make your own version of it, you’ll first need to set up the development environment by installing certain prerequisite tools for developing and running the platform on your personal computer. Then, you'll copy the platform's code to your computer and set up a database connection.

Setting up the development environment: dependencies

A project like the BOP Digital Platform generally integrates all or parts of other projects- that’s called a “dependency.” Those projects in turn might depend on other projects, so you can imagine how many projects and how many files you might need to access! Luckily, people in the open source development community have bundled many of these projects together into something that’s often referred to as a “package.”

Using a “package manager,” you can easily download many dependencies from a single place, rather than having to hunt for them. A package manager also provides easy access to all versions of a dependency, allowing an application to depend on specific versions known to work.

Depending on what operating system you’re running, you will need to use a specific package manager. To get the Digital Platform working on your computer, follow the directions for your operating system in one of the sections below. We’re assuming that most of our users are going to be running either macOS or Windows. (If you’re using Linux, you’ll use the package management facilities built into your distribution.)

You’ll ultimately download the following dependencies- make sure you download them in the order we’ve specified, because you’ll need some of these projects installed first in order to install the others.

• The package manager for your operating system
• Golang
• Pivot
• Diecast
• Python package manager
• Backend dependencies

You will also need to acquire credentials for the development database from the BOP Community Manager: [email protected].

---

For macOS

Installing Homebrew

By default, macOS does not come with a standard package manager for installing development tools (the Apple App Store is not the same as a package manager). “Homebrew” is a popular package manager used when developing software on Macs. To install it, go to the following URL and follow the instructions there: https://brew.sh/

Installing Golang

Golang (also called “Go”: https://golang.org/) is a statically-typed compiled language originally developed by Google that emphasizes speed, efficiency, and simple, easy-to-understand code. Golang is used in this project in the database abstraction and frontend templating modules (see next section).

To install Golang, open your computer’s terminal (you can find this by going to Finder > Applications > Utilities > Terminal). Paste the following command, then hit “enter”:

brew install go

Installing Golang dependencies: Pivot and Diecast

The platform uses two Golang projects, Pivot and Diecast, to “decouple” parts of the system from each other. This means that instead of being interconnected, the two components can exist separately. Decoupling is a popular concept in system architecture because it allows you to swap out components of a system without rewriting all of the individual parts.

Pivot

Pivot is a database abstraction service used to access, query, and aggregate data across a variety of database systems, written in Golang. In this project, Pivot is used to interact with the MongoDB database (https://www.mongodb.com/) we’re currently using. The benefit of using Pivot is that it allows you to write the backend code once, regardless of which (supported) database you use. (Usually, you write backend code that is specific to one/a handful of databases.) Pivot allows us to change or add databases in the future without rewriting the backend code.

To install Pivot, open your terminal, paste the following command, then hit “enter”:

go get github.com/ghetzel/pivot/pivot

Diecast

Diecast is a standalone web server that consumes REST services, passes the response into templates, and serves the results. This means that Diecast takes data from the platform’s database via the backend, puts it into the correct spots in a template, and creates the HTML, CSS, and/or JavaScript files that run in your browser. It’s typical for your choice of server-side templating languages to be constrained by your choice of backend language/framework. The benefit of using Diecast is that it allows you to build the frontend of a web application completely independently of the backend, without being locked into any particular backend language or framework.

To install Diecast, open your terminal, paste the following command, then hit “enter”:

go get github.com/ghetzel/diecast/diecast

Installing Python package manager (pip)

The backend of the BOP Digital Platform is written in Python. You’ll need to install a Python package manager called “pip” in order to install the backend’s dependencies.

To install pip, run these two commands in the terminal: curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py sudo python get-pip.py

Be prepared to enter your computer’s password in the terminal- the password won’t be visible while you’re typing, but if you mess up you can hit “ctrl + c” to do it over again.

---

For Windows

Windows: Installing Chocolatey

Chocolatey: https://chocolatey.org/

Windows: Installing Windows Subsystem for Linux (WSL) WSL: https://docs.microsoft.com/en-us/windows/wsl/install-win10

---

Getting the BOP Digital Platform’s code and running it locally (on your personal computer)

Forking and cloning the repository

In Github, copying a repository is called “forking.” Making a repository available for editing on your personal computer is called “cloning.”

To get the platform working on your computer, you’ll need to fork it and then clone it by visiting the project’s page here: https://github.com/BillionOysterProject/digital-platform-beta

If you’re unfamiliar with how to do this, read Github’s help documentation here: https://help.github.com/articles/fork-a-repo/

Set up database credentials

Take the database credentials that you were given by the BOP Community Manager and add them to the ~/.netrc file like so, replacing all of the bolded values with your credentials: echo ‘machine example-machine.mlab.com login example-username password example-password’ >> ~/.netrc

Building and running the project on your computer

In the terminal, change to the directory you cloned the platform’s source code to, then run the “make” command: cd digital-platform-beta make make run-development

Logging in to the BOP Digital Platform locally

In order to see your work while you’re developing, in your browser, go to: http://localhost:28419

Sign in with your platform credentials and you’re ready to go!