Apprise API

Contributing to Apprise API

Thank you for your interest in contributing to Apprise API.

This repository is the web application and API layer that wraps the Apprise core library. Contributions are welcome across code, bug fixes, UI improvements, documentation, and deployment tooling.

Retrieve from GitHub

git clone git@github.com:caronc/apprise-api.git
cd apprise-api

Development Environment

Apprise API supports both a local (bare metal) workflow and a Docker Compose workflow.

Bare Metal

Start the development server in debug mode:

tox -e runserver
# visit: http://localhost:8000/

You can also bind to a different address or port:

tox -e runserver -- "localhost:8080"
tox -e runserver -- "0.0.0.0:8080"

To run Apprise API against a specific Apprise core branch:

tox -e runserver -- --branch=1341-retries-and-priorities

When --branch is provided, the runserver environment force-reinstalls Apprise from that GitHub branch with pip caching disabled, so rerunning the command refreshes branch changes. Running tox -e runserver without --branch restores the PyPI Apprise package if the environment was previously switched to a branch.

Docker Compose for Development

A fresh checkout can be run with Docker Compose, and the development flow mounts your local source tree into the container so changes are reflected without rebuilding:

# Pre-create the paths you will mount to
mkdir -p attach config plugin

# Run the stack
PUID=$(id -u) PGID=$(id -g) docker compose up

Quality Assurance and Testing

This repository uses tox to keep linting, tests, and formatting consistent across contributor environments:

# Run unit tests
tox -e test

# Lint (calls ruff under the hood)
tox -e lint

# Auto-format
tox -e format

You can combine environments as well:

tox -e test,lint

If you prefer running tools directly (once dev dependencies are installed), the repository documents pytest and ruff as optional manual equivalents.

Interface Translations

The supported interface languages are defined in apprise_api/core/settings/__init__.py. Updating and compiling catalogs needs the GNU gettext tools (xgettext, msgmerge, and msgfmt) on your PATH; the Python development dependencies alone are not enough. When adding human-readable Python text, wrap it with Django’s gettext helpers. In templates, use {% trans %} for a short string or {% blocktrans %} for a longer passage. Do not translate JSON keys, enum values, status tokens, or other values that client software must interpret consistently. A value the API parses, such as success or text, stays English even where the words around it do not. Write apostrophes in translations as ’, never ': many translations sit inside JavaScript strings, where a straight quote breaks the page, and the translation report flags it.

After changing source text, update every catalog:

tox -e translations -- --update

The command reports each supported language and prints a bullet for every missing or fuzzy translation. Edit the matching file under apprise_api/locale/<language>/LC_MESSAGES/django.po, then run the read-only report until it is clean:

tox -e translations

Fuzzy entries are not accepted. Once the report is clean, compile the catalogs to check them and to try them locally:

tox -e translations -- --compile

Only commit the .po files. The compiled .mo files are ignored by git and are rebuilt automatically by tox -e runserver, the test suite, and every Docker image build, so each published image includes every language. With docker compose up for development, your local apprise_api/ folder is mounted over the image, so run the compile command above once first or every page shows in English.

When changing the shared layout, test a left-to-right language and Arabic on both desktop and a narrow phone. Text direction may change, but branding and related header controls should remain together.

Quick Checklist Before You Submit

• Your change includes tests when practical.
• tox -e test passes locally.
• tox -e lint passes locally.
• You ran tox -e format when formatting changes are needed.
• The translation report is clean when human-readable text changed.
• Your pull request description clearly explains what changed and why.

Notes on Docker Compose Files

• For development, docker compose up will apply the override file automatically in a fresh checkout, and it is designed for live iteration.
• For production-style deployments, prefer the base Compose file only, so you are running the immutable image and bundled static assets.

Licensing and Attribution

Apprise API is released under the MIT License

All contributions must be compatible with this licence, and new files should include appropriate headers where required.