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. This file can be empty, or environment overrides can be added as needed:

touch .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.

If DJANGO_ADMIN=true, 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