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://stage.boost.org/ - staging
- https://www.boost.org/ - production

---

## Local Development Setup

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

There are two options for development setups, nix and native. The native setup doesn't require nix to be installed. The nix-based setup works in a similar way to a python venv, with everything encapsulated for the project. Note: it is not a vm. It handles installation of all of the application and development environment's dependencies automatically:

- The python version relevant to the project
- awscli
- gdk
- just
- opentofu
- nodejs
- yarn
- asciidoctor
- asciidoctor-boost gem
- pre-commit
- black
- isort
- pip-tools


1. Development System setup
   1. Give your ssh key to Sam so he can add it to the boost.cpp.al server.
   1. Basic Setup Options:
      1. [Nix-based](docs/development_setup_notes_nix.md)
      1. [Native](docs/development_setup_notes_native.md)
   1. [Initial Data Setup](docs/first_time_data_import.md)
   1. [Allauth Social Login Setup](docs/allauth_setup.md)
1. System Concepts
   1. [GitHub Data Syncing](docs/syncing_data_with_github.md)
   1. [Rendered Content Caching](docs/caching_rendered_content.md)
   1. [Static Content from S3](docs/static_content.md)
   1. ['manage' Commands](docs/commands.md)
   1. [API](docs/api.md)
   1. [RSS Feeds](docs/rss_feeds.md)
   1. [Env Vars](docs/env_vars.md)
   1. [Calendar](docs/calendar.md)
   1. [News](docs/news.md)
1. Instructional
   1. [Dependency Updates](docs/dependencies.md)
   1. [Release Reports](docs/release_reports.md)
   1. [User Management](docs/user_management.md)
   1. [Non-Dev Server Allauth Setup](docs/non-dev-server-allauth-setup.md)
   1. [Admin Features](docs/admin.md)
   1. [Mailing List Setup](docs/mailing_list.md)

After going through the "Development System setup" steps above to create the Docker image, install dependencies, and start the services in `docker-compose.yml`, run:

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

# to create database migrations
$ just makemigrations

# to run database migrations
$ just migrate

# to create a superuser
$ just manage createsuperuser
```

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

```
# 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
$ just test
```

or run:

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

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

---

## Setting up Mailman/Hyperkitty locally

Note: This is optional - not required for the website to function, here for reference in case a need arises.

``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` (`lists_production_web` by default).

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

Create a database in your postgres instance called `hyperkitty_db`, then:

```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
apt update && apt -y install postgresql
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, `just manage 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 |

Example commands for running specific hooks:

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