phederation 0.8.2

Requirements

• Linux environment (tested on Mint/Ubuntu)

• Python (3.12+)

Installation

0. As a pip package:

If you want to build ActivityPub clients, you can use the software as a library.

pip install phederation

1. For development of the library, clone the repository from codeberg:

git clone https://codeberg.org/feldie/phederation.git phederation

2. Navigate to the root folder of the “phederation” repository, then set up a python environment with uv, e.g.:

cd phederation
uv sync

3. You can start a debug/development version using:

source .venv/bin/activate
gunicorn -c=settings/gunicorn.conf.dev.py

This will start a local server (localhost), you can try to access the fastapi doc at “<localhost:port>/docs”.

Testing and profiling

There are unit tests in the tests/ folder. They can be run using pytest:

pytest tests/unit_tests/

For coverage:

coverage run -m pytest tests/
coverage html

Profiling can be done with the pytest plugin pytest-profiling. For pretty svg plots of the runtimes, we use the additional graphviz tool.

pip install pytest-profiling
sudo apt install graphviz
pytest tests/unit_tests/ --profile-svg

Production environment

For a production environment, you should set up proper web hosting. Minimal safeguards should be in place, at least proxy+load balancing+ddos safe; nginx+fail2ban are a good combination:

• WSGI server (gunicorn: https://gunicorn.org/)

• Proxy and load balancer (nginx: https://nginx.org)

• ddos safeguard (fail2ban: https://github.com/fail2ban/fail2ban/wiki)

You should also use a proper WSGI webserver (e.g. gunicorn), see below. Phederation is set up to accommodate all of this, and is tested to work in a production environment. Example settings files for production can be found in the “settings” folder. After setting up fail2ban and nginx, you can start a production mode version like this:

source .venv/bin/activate
gunicorn -c=settings/gunicorn.conf.prod.py

The command above starts gunicorn workers and serves content on “127.0.0.1:8082” (localhost, then use proxy to serve on the web). It uses the settings file “settings/instance_config-prod.yaml” for production mode.

Of course, it is useful to convert this into a proper service that runs continuously. This can be done by containerization of the phederation server itself, building a docker image and then hosting it. It is important to first set the proper variables in the file settings/.env (an example file with dummy values is located in settings/.env.noignore), then build the docker image, and then start all docker images. Note that the docker compose file settings/compose.yaml will start a keycloak server, its postgres database, a mongo database for the phederation image, and the phederation image itself. If you have another keycloak server running already, you should disable the former in the settings/compose.yaml file and instead link to yours in the settings/.env file.

docker build -t phederation-0.5 .
docker compose up -d