Local setup

Running the Benefits application in a local, non-production environment requires Docker.

The following commands should be run in a terminal program like bash.

Clone the repository

git clone https://github.com/cal-itp/benefits

Create an environment file

The application is configured with defaults to run locally, but an .env file is required to run with Docker Compose. Start from the existing sample:

cp .env.sample .env

E.g. to change the localhost port from the default 8000 to 9000, add the following line to your .env file:

DJANGO_LOCAL_PORT=9000

See Configuration for more details on supported environment variables and their settings.

Run the build script

This builds the runtime and devcontainer images:

bin/build.sh

If you need all layers to rebuild, use:

docker compose build --no-cache client

Start the client

The optional -d flag will start in detatched mode and allow you to continue using the terminal session.

docker compose up -d client

Otherwise attach your terminal to the container’s terminal, showing the startup and runtime output:

docker compose up client

After initialization, the client is running running on http://localhost:8000 by default.

The backend administrative interface can be accessed at the /admin route using the superuser account you setup as part of initialization.

By default, sample values are used to initialize Django. Alternatively you may:

• Set environment variable values to use instead of the default sample values

Stop the running services with:

docker compose down