Metadata-Version: 2.4
Name: phederation
Version: 0.4.4
Summary: 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.
Author: Felix Dietrich
License-Expression: MIT
License-File: CONTRIBUTING
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Pydantic :: 2
Classifier: Framework :: FastAPI
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: build>=1.4.0
Requires-Dist: coverage>=7.10.7
Requires-Dist: cryptography>=45.0.5
Requires-Dist: fastapi[standard]==0.124.4
Requires-Dist: gunicorn[gevent]>=23.0.0
Requires-Dist: httpx>=0.27.2
Requires-Dist: mkdocs>=1.6.1
Requires-Dist: mkdocs-material>=9.7.1
Requires-Dist: mkdocstrings[python]>=1.0.0
Requires-Dist: psycopg2-binary>=2.9.10
Requires-Dist: pydantic>=2.11.7
Requires-Dist: pydantic-settings[yaml]>=2.10.1
Requires-Dist: pydeps>=3.0.1
Requires-Dist: pymongo>=4.15.3
Requires-Dist: pytest>=9.0.1
Requires-Dist: pytest-asyncio>=1.1.0
Requires-Dist: python-dotenv>=1.1.1
Requires-Dist: python-json-logger>=4.0.0
Requires-Dist: python-keycloak>=5.8.1
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: redis>=6.4.0
Requires-Dist: requests>=2.32.5
Requires-Dist: temporalio>=1.20.0
Requires-Dist: toml>=0.10.2
Requires-Dist: twine>=6.2.0
Requires-Dist: types-urllib3>=1.26.25.14
Requires-Dist: urllib3>=1.21.1,<2
Requires-Dist: uvicorn-worker>=0.3.0
Requires-Dist: uvicorn[standard]>=0.35.0
Requires-Python: >=3.12
Project-URL: Homepage, https://codeberg.org/feldie/phederation
Project-URL: Issues, https://codeberg.org/feldie/phederation/-/issues
Description-Content-Type: text/x-rst

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