AnimalTrakker Registry Web

This is an open-source project designed to help individuals and group track important information about their animals. You can find more information at our website here..

What is the "AnimalTrakker Registry Web"?

The web version of the AnimalTrakker ecosystem is a python-flask based web application that allows users to submit information regarding their animals to be processed by a central registrar. Currently, we support:

• Looking over your flock
• Submitting birth notifications
• Registering non-registered animals
• Transferring ownership of animals from one entity to another
• Updating any identification tags of any owned animal
• Search for all animals in a registry
• Search for all members in a registry
• Update personal contact information
• Mark animals as available for purchase or stud
• See all available animals in a registry

Installing Requirements

The requirements to be installed are stored in requirements/base.txt. To install them, navigate to the base of the repository and run pip install -r requirements/base.txt.

Registry Web Configuration

To configure the registry web, you will need to create a file titled at_registry_config.json. See registry_config for more context.

Email (optional)

at_registry_config.json may carry an optional email section. Without it the registry simply cannot send mail, which is a safe default — nothing fails, and startup logs Email not configured (disabled).

Because at_registry_config.json and .env are both gitignored, this section is the only committed record of the schema. Keep it current.

"email": {
  "provider": "mailersend",
  "fromAddress": "no-reply@your-verified-domain.org",
  "fromName": "Fine Fleece Shetland Sheep Association",
  "replyToAddress": "registrar@your-verified-domain.org",
  "mailersend": {
    "apiUrl": "https://api.mailersend.com/v1/email"
  }
}

allowedRecipients is the guard against a developer testing against a copy of live data and mailing a real member. When present, any send to an address not on the list fails and is logged at ERROR; matching ignores case and surrounding whitespace. Enforced in send_email, so no backend or feature can bypass it, and startup logs a warning naming every allowed address. Omitting the key means unrestricted — an empty list is rejected rather than read as "allow nothing".

Every subsection present is type-validated even when it is not the active provider's, so a complete mailersend block can sit in the file while running console. Switching providers is then a one-word edit against a block that has already been checked.

console writes messages to the application log instead of delivering them. It needs no credentials and no verified domain, which makes it the right choice for local development — but message bodies land on disk, so it must not be used in production. Startup logs a warning whenever it is active.

Credentials come from environment variables, never from the JSON:

A missing credential is a startup warning, not a startup failure — the registry stays up. The email feature disables itself instead: the Forgot your password? link is hidden and /auth/forgot-password returns 404, so no member is offered a form that cannot work. Startup prints a banner saying so, since the failure is otherwise invisible.

Running behind a reverse proxy

Set TRUSTED_PROXY_COUNT to the number of proxies in front of the app (1 for a single nginx). It defaults to 0, meaning the app is reached directly.

This is not optional when a proxy is present. Without it every request appears to come from the proxy, so anything keyed on the client address — notably the per-IP rate limit on password reset requests — shares one bucket across the whole registry, and members get silently throttled. It also lets the app know TLS was terminated upstream, so generated links use https rather than downgrading an emailed password-reset URL to http.

Leave it at 0 when the app is exposed directly. X-Forwarded-For can be set by any client, so trusting it without a proxy that overwrites the header would let a caller choose its own apparent address.

CLI Commands

Operator-only commands (creating staff users, etc.) are exposed via Flask's CLI. The repo ships a .flaskenv file so you do not need to set FLASK_APP yourself — just activate your venv and run:

flask --help                       # list all command groups
flask <group> --help               # list commands in a group
flask <group> <command> --help     # show options for a command

For example, to discover and use the user-management commands:

flask users --help
flask users create-staff --help

See cli/README.md for the list of available commands and how to add new ones.

Support

For support, please visit this link.