Boost.org Website

Overview

A Django based website that will power a new Boost website. See the documentation for more information about maintaining this project.

Links:

• https://www.stage.boost.cppalliance.org/ - staging
• https://www.boost.io/ - production

---

Local Development Setup

This project will use Python 3.11, Docker, and Docker Compose.

Instructions to install those packages are included in development_setup_notes.md.

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 database migrations
$ docker compose run --rm web python manage.py makemigrations

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

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

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

styles.css is still missing in a local docker-compose environment. Steps to add it:

# One-time setup
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
. ~/.bashrc
nvm install 20
nvm use 20
npm install -g yarn

# Each time - rebuild styles.css
yarn
yarn build  # or on windows: yarn dev-windows
cp static/css/styles.css static_deploy/css/styles.css

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

🔔 Updating the Docker image with new dependencies

If new dependencies exist in requirements.in, see Dependency Management for details on how to rebuild the Docker image with those new dependencies.

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

This is a one-time build that will generate the styles.css file. This file is currently generated by docker compose build and is included in the Docker image.

---

Generating Local Data

To add real Boost libraries and sync all the data from GitHub and S3, set appropriate values in your new .env file according to Environment Variables for GITHUB_TOKEN, STATIC_CONTENT_AWS_ACCESS_KEY_ID, STATIC_CONTENT_AWS_SECRET_ACCESS_KEY, STATIC_CONTENT_BUCKET_NAME, STATIC_CONTENT_REGION, STATIC_CONTENT_AWS_S3_ENDPOINT_URL then run:

docker compose run --rm web python manage.py update_libraries --local

Those values can be gotten from another developer in the #boost-website Slack channel.

The --local flag speeds up the command a lot by excluding the retrieval of data you generally don't need. For more information, see update_libraries in Management Commands.

Then as a superuser log into the admin interface, go to "Versions" and click on the "import new releases" button in the top right.

---

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

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