Skip to content

Install

Clone the repository

git clone https://github.com/WGBH-MLA/chowda.git
cd chowda

Install Chowda

PDM is used as the packaging manager. It can be installed with pip install pdm.

Install the project with development dependencies:

pdm install

Activate your virtual environment

$(pdm venv activate)
$() wrapper

Note: pdm venv activate outputs the command needed to activate your virtual environment. The $() wrapper evaluates it in your current shell context.

Deactivate the virtual environment

To return to your normal shell environment, run:

deactivate

Option 2: Install with pip

If PDM is not available, it can also be installed with pip. It is recommeneded to install to a virtual environment using venv:

python3 -m venv .venv
source .venv/bin/activate

Install the package

pip install .

Create database

Chowda needs to have a PostgreSQL server running and database named chowda-development (tests use a database chowda-test).

There are many ways to do this, but an easy way is to use docker. After starting Docker on your local machine, the following command will start a container using the postgres image in Dockerhub.

docker run --rm --name pg -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=chowda-development postgres

Command explained

  • docker run runs a docker container
  • --rm option will remove the docker container once it exits.
  • --name pg will name the running container pg so it can be identified when listing running containers.
  • -p 5432:5432 forwards port 5432 on your local machine to port 5432 (default postgres port) on the running container.
  • -e POSTGRES_USER=postgres sets ENV var on container for the postgres username

Security

Not a secure password, but that's ok for test and development environments.

  • -e POSTGRES_PASSWORD=postgres sets ENV var on container for postgres password

DB_URL environment variable

the environment variables values in the command must match the values that are part of the DB_URL environment variable specified in .env.development.

  • -e POSTGRES_DB=chowda-development sets ENV var on container for the name of postgres database to use

Database creation in docker

The postgres image will create the database when starting the container.

  • postgres is the name of the Docker image to use when starting the container.

Apply database migrations

alembic upgrade head

Run the application

The development server can be run with

pdm dev

Which is a shortcut for:

uvicorn chowda.app:app --reload

Visit: localhost:8000

Seed the database

To seed the database with fake data, run the seeds.py script:

python tests/seeds.py

Optional: Customize the number of records created by changing the num_* variables in the seed function.

Running tests

Chowda uses pytest for testing. Simply run:

pdm test

Which is the same as running:

pytest

Creating the test database and running a postgres server

For the tests to run successfully, it needs a dedicated test database. This can be done with docker, with the following command:

docker run --rm --name pg -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=chowda-test postgres