mirror of
https://git.sr.ht/~tsileo/microblog.pub
synced 2024-11-19 21:24:27 +00:00
81 lines
2.2 KiB
Markdown
81 lines
2.2 KiB
Markdown
# Developer's guide
|
|
|
|
This guide assumes you have some knowledge of [ActivityPub](https://activitypub.rocks/).
|
|
|
|
[TOC]
|
|
|
|
## Architecture
|
|
|
|
Microblog.pub is a "modern" Python application with "old-school" server-rendered templates.
|
|
|
|
- [Poetry](https://python-poetry.org/) is used for dependency management.
|
|
- Most of the code is asynchronous, using [asyncio](https://docs.python.org/3/library/asyncio.html).
|
|
- SQLite3 for data storage
|
|
|
|
The server has 3 components:
|
|
|
|
- The web server (powered by [FastAPI](https://fastapi.tiangolo.com/) and [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) templates)
|
|
- One process that takes care of sending "outgoing activities"
|
|
- One process that takes care of processing "incoming activities"
|
|
|
|
### Tasks
|
|
|
|
The project uses [Invoke](https://www.pyinvoke.org/) to manage tasks (a Python powered Makefile).
|
|
|
|
You can find the tasks definition in `tasks.py` and list the tasks using:
|
|
|
|
```bash
|
|
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](https://docs.microblog.pub/installing.html#python-developer-edition).
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
inv build-docs
|
|
```
|
|
|
|
And check out the result by starting a static server using Python standard library:
|
|
|
|
```bash
|
|
cd docs/dist
|
|
python -m http.server 8001
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Contributions/patches are welcome, but please start a discussion in a [ticket](https://todo.sr.ht/~tsileo/microblog.pub) or a [thread in the mailing list](https://lists.sr.ht/~tsileo/microblog.pub-devel) before working on anything consequent.
|
|
|
|
### Patches
|
|
|
|
Please ensure your code passes the code quality checks:
|
|
|
|
```bash
|
|
inv autoformat
|
|
inv lint
|
|
```
|
|
|
|
And that the tests suite is passing:
|
|
|
|
```bash
|
|
inv tests
|
|
```
|
|
|
|
Please also consider adding new test cases if needed.
|