Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


This repo specifies the web backend and frontend for the Orcasound app that plays a live audio stream through the user's browser of choice. The backend is an Elixir app using the Phoenix framework. The Phoenix app serves a React app.


Please check out the CONTRIBUTING doc for tips on making a successful contribution, as well as learning resources!

Getting started

Quick Start (e.g. at hackathons):

  • Load the Docker Configuration docker-compose pull && docker-compose up
  • Navigate to a new terminal in the same directory
  • Stop the containers by running docker-compose stop
  • Install the hex and npm dependencies by running docker-compose exec phoenix bash -c "mix deps.get && cd assets && npm install"
  • Restart your containers by running docker-compose up
  • Navigate to localhost:4000 to view the React app

Note: this assumes you have installed docker and docker-compose.

Detailed Setup

The fastest way to get the site up and running is to use the included Docker configuration.

To access the site, run docker-compose pull && docker-compose up and wait until the phoenix_1 container outputs Compiled successfully. Then you should find the site available in your browser at http://localhost:4000.

Note: The first time you load the docker configuration you will need to install the dependencies. Leave the phoenix_1 server running while navigating to a new command line tab inside the same directory. Then run docker-compose exec phoenix bash -c "mix deps.get && cd assets && npm install" which will install the node modules and hex dependencies. Now, navigate to localhost:4000 to view the running application.

Flexible method (e.g. longer-term development)

If you would like a more flexible method, you can install the dependencies directly on your machine.

Running in Docker

Docker is the quickest way to get the project up and running, especially if you haven't already set up Erlang/Elixir/Node. The only requirement is that you have both docker and docker-compose installed on your machine.

Once you clone the repository, you can just run docker-compose in the root directory. To avoid building locally you can use the pull command first to grab the pre-built image from Docker Hub. Combining both commands into one line:

docker-compose pull && docker-compose up

This will pull the pre-built image from Docker Hub along with an image for the database, automatically configure everything, and run the Phoenix server. The orcasite page will be accessible at http://localhost:4000 as soon as the phoenix_1 container outputs Compiled successfully.

Developing in Docker

At the moment, the docker-compose file uses bind mounting for the source files (assets, config, lib, test, mix.exs, and mix.lock), which means if you edit the source on your host file system, the changes will get picked up and hot reloaded in your browser.

However, please note that installed packages are not shared with the host file system, which means node packages and hexes need to be installed by running mix deps.get and npm install inside the phoenix container. The best way to do this is to use docker-compose exec

docker-compose exec phoenix bash -c "mix deps.get && cd assets && npm install"

The exec command can also be used to run any other commands that need to be completed in the container, like ecto.migrate and other database operations.

For more involved development you may want to access iex. To do this, stop the containers with docker-compose stop and start them back up using

docker-compose run --rm --service-ports phoenix iex -S mix phx.server

You will now have an interactive access to iex, while the postgres container runs in the background.

If you need more control over the dev setup, consider installing everything manually on the local machine.

Set up manually

If Docker doesn't suit your needs, you can follow these instructions to get everything running directly on your machine.



You will need to install Erlang, Elixir, and Nodejs. You can use a tool like asdf to manage your language dependencies.

Language-level dependencies can be found under .tool-versions. As of this writing, they are:

erlang 22.0.7
elixir 1.9.1-otp-21
nodejs 12.9.1


You will need to install Postgres and setup the postgres user with a password. The default connection details are:

username: "postgres"
password: "postgres"
database: "orcasite_dev"
hostname: "localhost"
port: 5432

You can pass in custom values using env variables. Full details can be found in dev.exs.

Orcasite uses PostGIS for location data inside of Postgres. To install on MacOS, run

brew install postgis

As of this writing, the following version numbers are used:

postgres 10.6
postgis 2.5.1


Once Erlang, Elixir, and Nodejs are installed, Postgres is running, and the repository has been cloned, install the project's dependencies with this command in the root directory:

mix deps.get

Set up the database with

mix ecto.create


mix ecto.migrate

Setting up the frontend requires npm. To set up the frontend:

cd assets


npm install

You can then return to the root directory

cd ..

The freshly created database is empty. To create a Feed in the database, run the seeds.exs file like this:

mix run priv/repo/seeds.exs

Finally, run the server with:

iex -S mix phx.server

You should now be able to see the page when visiting




From the assets folder

npx mocha


For the moment, this app is running in a Heroku instance with mix phx.server. To access the console, run:

heroku run POOL_SIZE=2 iex -S mix

The POOL_SIZE config var is necessary due to the current Postgres db having 20 connections. You can read more about it here.

Setting up Vagrant

Install Oracle Virtual Box

Install Vagrant

Spin up the vagrant box. This is a onetime setup that will take some time. Approximately 30 minutes.

$ vagrant up

SSH into the vagrant box

$ vagrant ssh

from the vagrant shell

vagrant@ubuntu-bionic:~$ cd /vagrant

Run all the mix, iex, npm and all other build type commands from the vagrant shell from the /vagrant directory or it's children.