NOTE: All of these various docker compose commands, along with other helpful developer utility commands, are codified in our justfile and can be ran with less typing.

You will need to install just, by following the documentation

Environment Variables: Copy file env.template to .env and adjust values to match your local environment. See Environment Variables for more information.

$ cp env.template .env

NOTE: Double check that the exposed port assigned to the PostgreSQL container does not clash with a database or other server you have running locally.

Then run:

# start our services (and build them if necessary)
$ docker compose up

# to create a superuser
$ docker compose run --rm web python manage.py createsuperuser

# to create database migrations
$ docker compose run --rm web python manage.py makemigrations

# to run database migrations
$ docker compose run --rm web python manage.py migrate

This will create the Docker image, install dependencies, start the services defined in docker-compose.yml, and start the webserver.

Access the site at http://localhost:8000.

Cleaning up

To shut down our database and any long running services, we shut everyone down using:

$ docker compose down

<<<<<<< HEAD

Environment Variables

See Environment Variables for more information on environment variables.

Wrap README at 79 cols

Running the tests

To run the tests, execute:

$ docker compose run --rm web pytest

or run:

$ just test

Yarn and Tailwind

To install dependencies, execute:

$ yarn

For development purposes, in a secondary shell run the following yarn script configured in package.json which will build styles.css with the watcher.

$ yarn dev

For production, execute:

$ yarn build

Generating Local Data

<<<<<<< HEAD

Sample (Fake) Data

To remove all existing data (except for superusers) from your local project's database (which is in its own Docker volume) and generate fresh sample data that will not sync with GitHub, run:

./manage.py create_sample_data --all

======= First, make sure your GITHUB_TOKEN is set in you .env file and run ./manage.py update_libraries. This takes a long time. See below.

Run ./manage.py generate_fake_versions. This will create 50 active Versions, and associate Libraries to them.

The data created is realistic-looking in that each Library will contain a M2M relationship to every Version newer than the oldest one it's included in. (So if a Library's earliest LibraryVersion is 1.56.0, then there will be a LibraryVersion object for that Library for each Version since 1.56.0 was released.)

Wrap README at 79 cols

For more information on the many, many options available for this command, see create_sample_data in Management Commands.

Live GitHub Libraries

<<<<<<< HEAD To add real Boost libraries and sync all the data from GitHub, run:

./manage.py update_libraries

This command can take a long time to run (about a half hour). For more information, see update_libraries in Management Commands.

======= There is not currently a way to generate fake Libraries, Issues, or Pull Requests. To generate those, use your GitHub token and run ./manage.py update_libraries locally to pull in live GitHub data. This command takes a long time to run; you might consider editing libraries/github.py to add counters and breaks to shorten the runtime.

Wrap README at 79 cols

Deploying

TDB

Production Environment Considerations

TDB

Pre-commit Hooks

We use pre-commit hooks to check code for style, syntax, and other issues. They help to maintain consistent code quality and style across the project, and prevent issues from being introduced into the codebase.

Pre-commit Hook	Description
Black	Formats Python code using the `black` code formatter
Ruff	Wrapper around `flake8` and `isort`, among other linters
Djhtml	Auto-formats Django templates
Rustywind	Sorts and formats Tailwind CSS classes

Setup and Usage

Description	Command
1. Install the `pre-commit` package using `pip`	`pip install pre-commit`
2. Install our list of pre-commit hooks locally	`pre-commit install`
3. Run all hooks for changed files before commit	`pre-commit run`
4. Run specific hook before commit	`pre-commit run {hook}`
5. Run hooks for all files, even unchanged ones	`pre-commit run --all-files`
6. Commit without running pre-commit hooks	`git commit -m "Your commit message" --no-verify`

Example commands for running specific hooks:

Hook	Example
Black	`pre-commit run black`
Ruff	`pre-commit run ruff`
Djhtml	`pre-commit run djhtml`
Rustywind	`pre-commit run rustywind`

Languages

HTML 66%

Python 27.4%

CSS 4.7%

Shell 0.9%

PowerShell 0.3%

Other 0.5%