mirror of
https://github.com/boostorg/website-v2.git
synced 2026-02-27 17:42:08 +00:00
162 lines
4.3 KiB
Markdown
162 lines
4.3 KiB
Markdown
# Boost.org Website
|
|
|
|
## Overview
|
|
|
|
A Django based website that will power a new Boost website
|
|
|
|
---
|
|
|
|
## 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 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:
|
|
|
|
```shell
|
|
$ docker compose down
|
|
```
|
|
|
|
## 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
|
|
```
|
|
|
|
---
|
|
|
|
## Generating Local Data
|
|
|
|
### 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:
|
|
|
|
```bash
|
|
./manage.py create_sample_data --all
|
|
```
|
|
|
|
For more information on the many, many options available for this command, see `create_sample_data` in [Management Commands](docs/commands.md).
|
|
|
|
### Live GitHub Libraries
|
|
|
|
To **add real Boost libraries and sync all the data from GitHub**, run:
|
|
|
|
```bash
|
|
./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](docs/commands.md).
|
|
|
|
---
|
|
|
|
## 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 |
|
|
| [Rustywind](https://github.com/avencera/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` |
|