Plenario

The Premier Open Data Platform

Open RFCs

We encourage everyone to participate in this project — filing bugs, opening feature requests, etc. One of the most impactful areas is participating in open RFCs specifically. You can find the list of currently active RFCs here.

Development Software Prerequisites

Plenario is primarily written in the super-fast, functional Elixir. This lets us operate on huge amounts of data in the blink of an eye; unfortunately it also means setting up a Plenario development environment is a little more involved than the average GitHub project. Follow the steps below, though, and we'll have you up and running in no time!

With the rapid development of Elixir, we want to be deliberate about which tool versions we are using when working with the code. We use asdf to automate management of our Erlang, Elixir, and Node environments, but you can do it manually if you're feeling bold. We also use Docker to set up our Postgres database for development and testing and to provide a consistent environment when building releases.

Erlang, Elixir, and Node

Using asdf

First make sure you have asdf installed and configured properly. Instructions for doing so are available here. Make sure to install the system packages listed at the end of those instructions.

You'll also need the Erlang, Elixir, and Node plugins for asdf. You can check your list of installed plugins with

$ asdf plugin-list
elixir
erlang
nodejs

and add any missing ones with

asdf plugin-add erlang
asdf plugin-add elixir
asdf plugin-add nodejs

Now you can just enter the project directory and run

asdf install

to automatically install the correct versions of all three tools. When inside the project directory tree you'll automatically and transparently use the correct tool version when calling commands, e.g. mix.

Manually

If you don't want to use asdf, perhaps because you already have other version managers running like nvm or kerl, you can find our currently employed versions of Erlang, Elixir, and Node listed in human-readable format in .tool-versions. Install them globally or with your version managers of choice, and make sure you're using them when working on Plenario.

Yarn

We use Yarn to manage our JavaScript dependencies. While NPM has made great strides in the last few versions to match the "killer features" of Yarn, such a rapid release schedule comes with reliability issues. As such, we still prefer the stability afforded by Yarn.

Please refer to the Yarn documentation for installation instructions.

Docker and Postgres

We use Docker to stand up our local development database environment with Postgres+PostGIS. We also use it to provide a consistent, Ubuntu-based build environment to ensure a version of Plenario built on any development machine will run just as well in the production environment.

Installing Docker

We highly recommend using the latest instructions and installation packages from Docker themselves, especially on macOS and Windows. The new Docker for Mac/Windows distributions use the native virtualization technologies under those operating systems, and so should be more performant than the standard VirtualBox distribution.

• Docker for Mac
• Docker for Windows
• Linux
  • CentOS
  • Debian
  • Fedora
  • Ubuntu
  • Binaries (you might also be able to find docker in your distro's default package repository)

Postgres+PostGIS

Plenario expects to connect to a Postgres database with the PostGIS extension enabled. Rather than setting that up yourself, you can pull down a pre-configured Docker image with

docker pull mdillon/postgis

Project Dependencies

NOTE
We recommend repeating this step every time you check out a new git branch. Installed dependencies are not tracked in git and will not update automatically when changing branches.

One last step; we need to install the Elixir plugins and Node modules that Plenario depends on. Run the following from the project root:

mix deps.get
cd assets/
yarn

You're all set! Read Running Development Server to get started contributing, and Running Test Suite learn how to run our automated test suite.

Running Development Sever

NOTE
Remember to re-run the commands in Project Dependencies if you have checked out a different branch. Git can't update them automatically.

Once you're sure you've got all of your software prerequisites set up, you're ready to get started! This requires just a couple steps:

# Stand up the development database and populate it
docker run -dp 5432:5432 -e POSTGRES_PASSWORD=password mdillon/postgis
mix ecto.create
mix ecto.migrate

# Start the Phoenix server
mix phx.serve

Now you can access the Plenario front end at http://localhost:4000 and the API via http://localhost:4000/api/v2/.... HTML/style changes will live update in your browser, and most API changes will be visible the next time you call the endpoint.

To stop the Phoenix server, press Ctrl-C twice. You can stop the Postgres container with the usual docker container stop <container name/hash>.

For more specific information on the locally running server, check the Phoenix Framework documentation.

Sample Data

By default, the development server is empty; it doesn't have any users, data sets, or Array of Things networks. You can add them manually as needed, but we also offer the following command to quickly create a Plenario user with administrator privileges and some sample data.

mix run priv/repo/seeds.exs

The created user has these login credentials:

• Email: [email protected]
• Password: password (yes, we know)

Running the Test Suite

NOTE
Remember to re-run the commands in Project Dependencies if you have checked out a different branch. Git can't update them automatically.

First make sure you've got all of your software prerequisites set up. Then run the following from the project root to execute the automated tests.

# Stand up the test database and populate it
docker run -dp 5432:5432 -e POSTGRES_PASSWORD=password mdillon/postgis
MIX_ENV=test mix ecto.create
MIX_ENV=test mix ecto.migrate

# Run the tests
mix coveralls

If during development you need to make configuration changes, do that in the config/test.exs file. If your tests work locally, but something is screwy on Travis, update the config/travis.exs file.

Building and Deploying Releases

Deployments are built using a Docker container and sent to the target host where they are swapped in for the running version.

To create a fresh release archive and deploy it, all you need to run is

make deploy

NOTE: The defaults for deployments assume you have a .ssh/config file on your machine and that it has a dev entry for the application host. The deployment uses SSH and you must be able to connect to the host machine.

Specifying a Host Target

If you need to specify a non-default hostname, run the deployment command as

make deploy HOST=some-host-name

Running Migrations

If you need to run migrations before starting the release, run the deployment command as

make deploy MIGRATE=true

Running the Seed Script

If you need to run the seed script before starting the release, run the deployment command as

make deploy SEED=true

NOTE: This will also run all unapplied migrations against the database.