website-v2/README.md

# Boost.org Website

## Overview

A Django based website that will power a new Boost website. See the [documentation](./docs/README.md) 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](docs/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](https://just.systems/man/en/)

**Environment Variables**: Copy file `env.template` to `.env` and adjust values to match your local environment. See [Environment Variables](docs/env_vars.md) for more information.

```shell
$ 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:

```shell
# 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:

```shell
$ docker compose down
```

### :bell: Updating the Docker image with new dependencies

> If new dependencies exist in `requirements.in`, see [Dependency Management](docs/dependencies.md) for details on how to rebuild the Docker image with those new dependencies.

## Running the tests

To run the tests, execute:

```shell
$ docker compose run --rm web pytest
```

or run:

```shell
$ just test
```

## Yarn and Tailwind

To install dependencies, execute:

```shell
$ 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.

```shell
$ yarn dev
```

For production, execute:

```shell
$ 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](docs/env_vars.md) 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:

```bash
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](docs/commands.md).

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

---

## Setting up Mailman/Hyperkitty locally
``shell
sudo apt-get install sassc
git clone git@gitlab.com:mailman/hyperkitty.git
cd hyperkitty
cp example_project/settings.py example_project/settings_local.py
pip install -e '.[dev]'
pip install psycopg2-binary
``
change settings.py to use postgres database:
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
Update database values in settings to use the same host, user, password, and the database name as in the .env file value for `HYPERKITTY_DATABASE_NAME`.

run `django-admin migrate --pythonpath example_project --settings settings`

Give your ssh key to Sam so he can add it to the boost.cpp.al server, and then download the mailman db archive and cp the sql to the docker container
```shell
scp {user}@staging-db1.boost.cpp.al:/tmp/lists_stage_web.staging-db1-2.2025-02-06-08-00-01.sql.gz .
docker cp lists_stage_web.staging-db1-2.2025-02-06-08-00-01.sql website-v2-web-1:/lists_stage_web.staging-db1-2.2025-02-06-08-00-01.sql
docker exec -it website-v2-web-1 /bin/bash
psql -U postgres -W hyperkitty_db < /lists_stage_web.staging-db1-2.2025-02-06-08-00-01.sql
```

## Syncing EmailData Locally

To work with mailinglist data locally, the django application expects to be
able to query a copy of the hyperkitty database from HYPERKITTY_DATABASE_NAME.
Then, the `sync_mailinglist_stats` management command can be run.

## Deploying

TDB

## Production Environment Considerations

TDB

---

## Pre-commit Hooks

We use [pre-commit hooks](https://pre-commit.com/) 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](https://github.com/psf/black) | Formats Python code using the `black` code formatter |
| [Ruff](https://github.com/charliermarsh/ruff) | Wrapper around `flake8` and `isort`, among other linters |
| [Djhtml](https://github.com/rtts/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` |