Fish club auctions

A free, full featured auction platform:

• Run online or in-person auctions
• Reserve and buy now prices
• Automatic invoicing
• Integrated payment processing with PayPal and Square
• Using a projector, show pictures of lots as they are auctioned off
• Users don't need to create an account for in-person auctions
• Support for Breeder Award Programs/Breeder Participation Programs
• Easily copy lots, rules, and users between auctions
• One click export of data to generate marketing lists
• Different seller and club cuts for club members
• Support for multi-location auctions and mailing of lots
• A recommendation system to find lots in large auctions
• Dozens of stats including web traffic, auctioneer speed, lot sell prices over time, and more to help optimize your next auction
• and more!

What started as a free and open source tool to allow fish clubs to run online auctions during COVID has grown into the best club auction platform available, used by dozens of clubs and thousands of users! If you are part of a club looking to run an auction, please visit the site here

If you have a suggestion or are a developer who would like to contribute, read on.

Features and issues

I'm open to adding new features that make the site better - large or small. Open a new issue with your suggestions or bug reports. Please include as much detail as possible.

Development

Getting started

This project is packaged in Docker, so assuming you have docker installed, you should be able to just:

git clone https://github.com/iragm/fishauctions
cd fishauctions
./update.sh
docker compose --profile "*" build
docker compose up -d

You should now be able to access a development site at 127.0.0.1 (Note: unlike most Django projects, you probably won't use port 8000)

Enter the username admin and the password example, and you should be good to go.

Setup checklist: The setup checklist is not in the site's menus; it's read through the admin-only MCP endpoint (see Deploy the website). On a local site, the comments in .env.example cover the same settings.

Demo data: In development mode (DEBUG=True), demo data loads automatically when the database is empty (skipped when SINGLE_CLUB_MODE is on).

Creating a user: This is done automatically, but you can create additional users with (admin/example shown below):

docker exec -it django python3 manage.py shell -c "from django.contrib.auth import get_user_model; User=get_user_model(); u=User.objects.create_superuser('admin', '[email protected]', 'example'); u.emailaddress_set.create(email=u.email, verified=True, primary=True)"

A few notes on development environments

The .env.example doesn't document everything, but it has the most common settings. For example, if you use port 80 for something else, you could serve up the development site on a different port by editing your .env file to have the line HTTP_PORT=81

Some stuff (like Google Maps) won't work without an API key. When generating your API key, make sure to include the port number you use if it's not port 80, for example, http://127.0.0.1:81 if you use port 81

Production environment differences

At this time, I'm only aware of one production deployment, but since this is open source, you're welcome to spin up your own competing website.

In keeping with 12 Factor, all configuration is done from the .env file and the rest of the environment is kept extremely similar, but:

• Production uses SWAG to add a cert, dev uses plain old Nginx to serve just http content.
• Production uses Gunicorn with a Uvicorn worker process, development uses Uvicorn with a --reload flag (this is configured in entrypoint.sh)

Adding packages

New packages can be added to requirements.in (in addition to the standard Django settings file) for production dependencies, or requirements-test.in for test dependencies. Then run ./.github/scripts/update-packages.sh to generate updated requirements.txt files.

If you would like to upgrade all packages to the latest supported version, run ./.github/scripts/update-packages.sh --upgrade

Running tests and lints

To run the same set of tests and lints that would be run in CI, run docker compose run --rm test --ci. This will fail if changes are required. There are additional commands below that can be used to run individual test/lint components and auto-fix issues where possible.

Auto-formatting

To format code, run docker compose run --rm test --format. This will attempt to auto-fix issues, if possible.

To check if code is formatted properly without modifying any files on disk, run docker compose run --rm test --format-check. The command will output failures (if any) and exit with an error if changes need to be made.

Linting

To lint the code, run docker compose run --rm test --lint. This will run a full linting suite and attempt to auto-fix problems.

To check if code passes the linting check without modifying any files on disk, run docker compose run --rm test --lint-check. The command will output failures (if any) and exit with an error if changes need to be made.

Management commands

Run these with docker exec after docker compose is up. For example: docker exec -it django python3 manage.py makemigrations

Speaker directory

The directory at /speakers/ was seeded once from a WordPress export of the Northeast Council's old site (Tools → Export; export files are gitignored). A one-time job, kept in case it needs a re-run — each command's --help and module docstring has the details:

manage.py import_nec_speakers <export.xml>              # --dry-run first; re-running updates, never duplicates
manage.py import_nec_speakers <export.xml> --topics-only  # re-apply just the topics after the vocabulary changes
manage.py geocode_speakers                              # LLM reads the bios for a location, then geocodes it
manage.py split_speaker_talks                           # LLM splits the flattened "Programs:" run-on

Topics are a closed vocabulary (auctions/speaker_topics.py) — nothing in the UI coins a new one. Access needs any club permission in a club flagged NEC member club in the Django admin.

Developing in VSCode

This project is optimized for development in Visual Studio Code. If you are using VSCode, begin by installing the "Remote Development" extension pack, and make sure Docker is also installed.

Working in a VSCode development container will ensure that all project dependencies are installed--aiding in running the Python language server, IDE auto-completion, running tests automatically, etc.

To begin, follow the VS Code prompt to Reopen in Container. The first time running this command will take a while as the remote development container is built. You can also open this project in a remote container by opening the command palette (CMD+Shift+P), and navigate to Dev Containers: Reopen in Container.

Pre-Commit Hook

You can optionally enable a pre-commit hook that will ensure code auto-formatting and linting has run before you commit your change. While not necessary, it can help make sure a commit will pass CI before it is pushed.

To install on your local machine, install via pip install pre-commit, then run pre-commit install to register this project's pre-commit hooks.

By default, pre-commit only runs on files that were changed. When installing pre-commit for the first time, you can optionally run pre-commit run --all-files to run the hooks against all files.

Running your own auction website

Support for you running your own auction website is extremely limited (read: non-existent). That said, here's the basics of getting started.

Pre setup checklist:

• Register a domain name with your favorite registrar. I like Cloudflare, it also provides free DDOS protection and caching.
• Purchase a VM. I use Hostinger. I don't love them, but they're cheap. They're fine. Grab a KVM2 and use this referral code to get 20% off. I use and recommend Ubuntu as the OS.

Deploy the website

Log into your VM and enter the following:

git clone https://github.com/iragm/fishauctions
cd fishauctions
./update.sh

./update.sh will initialize the environment for you, including generating secure secrets.

After the site starts, sign in as a superuser (username=admin, password=example, make sure to change these!). The setup checklist is only on the site's admin MCP endpoint, not in its menus: in Claude, add a custom connector with the URL https://yourdomain/mcp/admin/, sign in as that superuser, and ask it to read the setup checklist (read_admin_page with page admin_setup_checklist). Only clients listed in MCP_ADMIN_CLIENT_IDS can connect; claude.ai is the default. The checklist points you at the .env file, shows which settings and integrations are configured, and gives copy/paste .env examples and where-to-get-keys links for Gmail, SES, PayPal, Square, Google Maps, Google sign-in, reCAPTCHA, Mailchimp, Google Calendar, Discord, digital membership cards, and the natural-language command palette assistant.

Everything on the checklist is free except the command palette assistant, which bills per use to whichever model provider you point it at. It's off unless you set OPENAI_API_KEY; the admin MCP's command_palette_analytics report shows what it's costing.

Work through the checklist, at a minimum you'll need Gmail for email, Google Maps and Recaptcha v2, everything else is optional (but recommended).

Post setup:

Go to the Django admin site (it's in the admin dropdown menu) and update the categories and FAQ articles to suit your tastes.

Note that the Django admin site is barely used in production. I use it to:

• Add blog posts, categories, and FAQs
• Give users super user permission, and permission to create lots/auctions

Everything else can be done through the UI.

Note: Do not remove the default "Uncategorized" category, it's referenced in several places in the code. It's fine to remove the other default categories.

If you let users upload photos, you need a DMCA agent

This one isn't optional and no software can do it for you. Your users upload photos of their fish, which makes you a service provider hosting somebody else's material. US law (17 U.S.C. 512) shelters you from what they upload only if you register a designated agent with the Copyright Office at dmca.copyright.gov/osp -- $6, and it lapses after three years -- and publish that agent's details on your own site.

Once you've registered, set the DMCA_* variables in your .env (they're in .env.example, and the setup checklist on the admin MCP has copy/paste examples). The site then publishes them at /dmca/ with a takedown form, a counter-notice policy and a three-strike repeat-infringer policy, and links to it from the footer and the About menu. Leave them unset and that page stays off, which is the right default for a fork -- publishing somebody else's agent would be worse than publishing none.

Two things to do alongside it: say the same thing in your tos.html (users have to be told about the repeat-infringer policy for it to count), and set CLOUDFLARE_ZONE_ID and CLOUDFLARE_CACHE_PURGE_API_TOKEN if you run behind Cloudflare, so a removed photo actually leaves the CDN instead of being served from the edge for another month.

Updates:

Updates can be run by typing ./update.sh in your VM.

To update without prompts (from cron, say), run ./update.sh -y, or set DEPLOY_UNATTENDED=1 for runs with no terminal. That answers yes to the snapshot question, so take snapshots some other way.

Very rarely following an update I've needed to run docker compose down && docker compose up -d instead of just running update, so if the site isn't coming back after an update, give this a try before rolling back to your snapshot.