octopod/Development_guide.md

Development guide

Git flow

master contains the latest "release version" only.

All development should be done in the develop branch.

Feature PRs are created to the develop branch and merged with all commits squashed. This leads to us having every commit in the develop branch corresponds to exactly one feature or bug fix.

When a release is ready, the develop branch is merged into the master branch using rebase and merge. This makes the master branch have every commit be a feature or bug fix. Merging to master triggers a CI script that collects all commits since the last merge and creates a new release with a change log of all commits.

Building

Nix Installation

Everything is built with nix. To build the project you will need to install it.

curl https://nixos.org/nix/install | sh

Nix cache

Reflex platform cache

To speedup initial project builds you will want to set up the Reflex Platform binary nix cache – append the following to /etc/nix/nix.conf:

binary-caches = https://cache.nixos.org https://nixcache.reflex-frp.org
binary-cache-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= ryantrinkle.com-1:JJiAKaRv9mWgpVAz8dwewnZe0AzzEAzPkagE9SP5NWI=
binary-caches-parallel-connections = 40

Octopod cache

The Octopod cache will also be useful to speed up builds:

1. Install Cachix:

   nix-env -iA cachix -f https://cachix.org/api/v1/install
   

2. Add cache:

   cachix use octopod
   

Development

We have written a Makefile with common targets used during development.

Building

• build-backend – builds a release backend executable.
• build-octo-cli – builds a release octo CLI executable. NOTE: this is not the octo CLI executable that is used for distribution but the dependencies are close enough for development purposes.
• build-frontend – build the frontend release.

Development

For development, we have set up ghcid commands that rebuild the project every time you make a change. The targets should self-explanatory:

• ghcid-backend
• ghcid-cli
• ghcid-frontend

Running the project locally

We have two commands to run the backend and frontend in the Makefile:

• run-backend-dev

  Builds a production version of the backend server, runs database migrations and starts the server with mock control scripts. You can see the used config in dev/dev_backend.sh.

  NOTE:

  1. You need to have a Postgres database running on localhost:5432 (the default port).

  2. You need to create an empty octopod database.

  3. You also need to have an octopod:octopod user set up as it will be used by the server to access the database.

     The easiest way to do this is by running the following command after you have Postgres running:

     psql -c "CREATE ROLE IF NOT EXISTS octopod WITH PASSWORD 'octopod' SUPERUSER LOGIN;"
     

  4. You will need sqitch installed on your system as it will be used to run migrations on the database.

• run-frontend-dev

  Build a production version of the frontend and runs it locally, pointing it to the locally running backend server.

  NOTE:

  You need to have Caddy 2 installed on your system as it is automatically used as a proxy.

Stack

For convenience, the repo currently also contains a stack.yaml that can be used for development. It is only used to build the macOS octo CLI release but supports building both octo CLI and the Octopod Server in an environment close enough to the release environment to be useful during development if you prefer stack.