microblog/docs/developer_guide.md

2.2 KiB

Developer's guide

This guide assumes you have some knowledge of ActivityPub.

[TOC]

Architecture

Microblog.pub is a "modern" Python application with "old-school" server-rendered templates.

  • Poetry is used for dependency management.
  • Most of the code is asynchronous, using asyncio.
  • SQLite3 for data storage

The server has 3 components:

  • The web server (powered by FastAPI and Jinja2 templates)
  • One process that takes care of sending "outgoing activities"
  • One process that takes care of processing "incoming activities"

Tasks

The project uses Invoke to manage tasks (a Python powered Makefile).

You can find the tasks definition in tasks.py and list the tasks using:

inv -l

Media storage

The uploads are stored in the data/ directory, using a simple content-addressed storage system (file contents hash is BLOB filename). Files metadata are stored in the database.

Installation

Running a local version requires:

  • Python 3.10+
  • SQLite 3.35+

You can follow the Python developer version of the install instructions.

Documentation

The documention is managed as Markdown files in docs/ and the online documentation is built using a homegrown Python script (scripts/build_docs.py).

You can build the documentation locally by running:

inv build-docs

And check out the result by starting a static server using Python standard library:

cd docs/dist
python -m http.server 8001

Contributing

Contributions/patches are welcome, but please start a discussion in a ticket or a thread in the mailing list before working on anything consequent.

Patches

Please ensure your code passes the code quality checks:

inv autoformat
inv lint

And that the tests suite is passing:

inv tests

Please also consider adding new test cases if needed.