phederation 0.4.4
Phederation implementation of ActivityPub. Can be used to setup a server in the fediverse, and can also be used as a library to build clients connecting to these (and other ActivityPub) servers.
Requires Python: >=3.12

A python/fastAPI implementation of the ActivityPub protocol.

Requirements
============
 - Linux environment (tested on Mint/Ubuntu)
 - Python (3.10+)

Installation
============

0) As a pip package:

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

.. code-block:: sh

   pip install phederation

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

.. code-block:: sh

   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, e.g.:

.. code-block:: sh

   cd phederation
   python3 -m venv .venv


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

.. code-block:: sh

   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:

.. code-block:: sh

   pytest tests/


For coverage:

.. code-block:: sh

   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.

.. code-block:: sh

   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 (including creating a logs folder if it does not exist yet):

.. code-block:: sh

   source .venv/bin/activate
   mkdir logs
   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.

.. code-block:: sh

   docker build -t phederation-0.1
   docker compose up -d