Developer Setup

This document describes how to get a development environment configured for modifying or contributing to EDD. This page is assuming that typical development tools (like git) and specific tools used by EDD (like docker and pre-commit) are installed already. If they are not installed, there are separate guides for macOS and Linux pre-requisites.

Clone the repo

It would be difficult to start developing on EDD without the code! So step 1:

git clone https://github.com/JBEI/edd.git

Install pre-commit hooks

We are using pre-commit to do some basic sanity checks on code. This tool runs various linters and checks on every commit, and makes sure that code is up to some minimum standards at all times. This only needs to be run once per clone:

pre-commit install

Configure

EDD includes a script to handle creating basic initial configuration. This script will:

  • Test your git configuration
  • Copy sample configuration files
  • Generate random passwords for use in autoconfiguring EDD’s Docker services
./bin/dev_quickstart.sh

Configure settings

While optional, this step is highly recommended, if only to enable features like emailing yourself when errors occur, or making use of Django DEBUG features and the Django Debug Toolbar. The script will place a file at settings/__init__.py, containing Django settings overrides.

Some additional changes to aid in development can be made by changing these Django settings. Add support for the Django debug toolbar in the settings directory to run EDD with a helpful debug application. This will add an expandable toolbar to every page, showing information like request headers, SQL queries run, template context, signals fired, etc.

Configure secrets

The dev_quickstart.sh script will create a secrets directory, containing generated passwords and connection URLs for services. These passwords are set in the service data volumes on first launch; to use alternate passwords or existing services (e.g. if you already have a Postgres cluster), edit the file prior to launching EDD.

Pull EDD’s images

Running docker compose up will automatically pull any missing Docker images to the host prior to launching; however, it is sometimes useful to run this step manually. Building or pulling specific images, and tagging appropriately, allows more control over the images used to launch EDD.

See the documentation on the jbei/edd-core image for details on building and running the core application components. More details on all the components can be found in the Docker Infrastructure documentation.

Launch EDD

You can run EDD either on a single Docker node with docker compose up -d, or use a Docker Swarm with docker stack deploy -c [CONFIG] [STACK]. Create a config file by running docker compose config and saving the output.

Install ICE

Running bin/dev_quickstart.sh will configure EDD to launch with an ICE instance appropriate for local-only testing. An external instance may also be configured by creating a random key like so:

openssl rand -base64 64 | tr -d '\n' > secrets/edd_ice_key

Then copy this shared secret to both the target ICE instance and EDD.

Front-end Development

The EDD makes use of Node.js packages for managing front-end code. All dev dependencies are contained in a Docker image, in a build stage used to prepare front-end assets. You can build the Dockerfile with a --target typescript flag to get an image used for local development of the front-end code.

EDD uses TypeScript for its client-side interface, and compiles JavaScript with third-party libraries using Webpack. The static asset files for the frontend are bundled with the jbei/edd-core image; however, running a full Docker build following any change to the TypeScript code, will be inefficient. To avoid this, follow these configuration steps to get changed TypeScript deployed to a running EDD without a full build.

Launch EDD

This will typically be docker compose up -d, or docker stack deploy. The compose file used to launch should have an override to load code in from the host to a volume mounted at /code. This should already be in place when using the bin/dev_quickstart.sh script.

Edit and Compile Typescript

Use the bin/local_typescript_shell.sh script to launch a container for the EDD TypeScript environment. Inside the TypeScript container shell, execute yarn local to do a one-time local build, or yarn watch to monitor changes and run incremental builds on save.

Refresh static files in EDD

Once static files are compiled, use the refresh_static.sh command in an EDD container built in dev mode. This command will copy any changed static files so they can be served, and update the internal Django settings used by EDD to identify the currently active static files.