Developer Environment Setup¶

The instructions here are for macOS; where appropriate, they'll proffer a Linux equivalent.

Info

Because I don't develop on Windows, I don't have equivalent instructions for setting up there. I would welcome Windows versions of these instructions!

Install your dependencies¶

On macOS, that means installing the following:

Just
gsed
uv
Docker (with the compose addon)

For simplicity, these instructions assume that you have Homebrew installed. After installing each tool, set your PATH appropriately as needed.

Just

Just is a task runner; it uses a Justfile to describe steps to run, and I use it here to manage the setup and development processes.

Install it from your package manager:
```
$ brew install just
$ just --version
just 1.16.0
```
gsed

gsed is required on MacOS to run several scripts that bootstrap the Python environment. Linux environments are fine with just sed.
```
$ brew install gnu-sed
$ gsed --version
gsed (GNU sed) 4.9
```

uv

uv is a Python package and project manager.

$ brew install uv
... lots of output
$ uv -V
uv 0.6.6 (c1a0bb85e 2025-03-12)

Docker compose

"Installing Docker" is beyond the scope of this document. You probably want Docker Desktop. Once it's installed and running, this should work:
```
$ docker compose ps
NAME                IMAGE               COMMAND                  SERVICE             CREATED             STATUS              PORTS
```
For most of the development process, Docker is only used to run the local PostgreSQL, Redis, and mailcatcher components used in testing and locally running the site.

Bootstrap Your Development Environment¶

Once you have all the dependencies installed, you can bootstrap your development environment:

$ just bootstrap

This command will:

Check for the .env file (creates it if missing)
Start Docker services (PostgreSQL, Redis, Mailcatcher)
Collect static files
Run database migrations
Load initial fixture data
Seed a complete test election with realistic data

What Gets Created¶

The just bootstrap command creates a complete test election called "The Yugo Awards" with:

Election & Categories: 21 official Hugo Award categories with proper field definitions
Test Users: Admin user (username: admin, password: admin) and test members
Nominations: 100 members with realistic nomination variations and typos
Canonicalizations: Grouped nominations into works
Finalists: Top 6 nominated works per category, plus "No Award"
Votes: 50 members with ranked ballots

You can access the admin interface at http://localhost:8000/admin/ using the admin credentials.

Manual Seeding Commands¶

If you need more control over the test data, you can use individual seeding commands:

Quick Start: All-in-One Command¶

# Create a complete election with default settings
$ uv run manage.py seed_all my-election "My Test Election"

# Quick mode: smaller dataset (20 nominators, 30 voters)
$ uv run manage.py seed_all my-election "My Test Election" --quick

# Full mode: larger dataset (200 nominators, 300 voters)
$ uv run manage.py seed_all my-election "My Test Election" --full

# Clear existing data before seeding
$ uv run manage.py seed_all my-election "My Test Election" --clear

Individual Commands¶

For granular control, use these commands in order:

Create Election and Categories:

$ uv run manage.py seed_election my-election "My Test Election"

Generate Nominations (creates members and their nominations):

$ uv run manage.py seed_nominations my-election --count 50

Canonicalize Nominations (group similar nominations):

$ uv run manage.py seed_canonicalizations my-election

Create Finalists (select top nominated works):

$ uv run manage.py seed_finalists my-election --count 6

Generate Votes (create ranked ballots):

$ uv run manage.py seed_ranks my-election --count 100 --new-members

Useful Flags¶

--clear: Remove existing data before seeding
--count N: Specify number of members/voters to create
--quick / --full: Preset dataset sizes (for seed_all)
--new-members: Create new voters instead of reusing existing members
--categories "Category Name": Limit to specific categories

Resetting Your Environment¶

To completely reset your development database:

$ just down      # Stop and remove Docker containers
$ just bootstrap # Rebuild from scratch

Running the Development Server¶

After bootstrapping, start the development server:

$ just serve

The site will be available at http://localhost:8000/ (or the port configured in your .env file).

Viewing Emails¶

All emails sent by the application are captured by Mailcatcher. To view them:

$ just mailcatcher

This opens Mailcatcher's web interface in your browser.