From f9ee3ef69d7e3c91a3df6bad949d25a24baf57b0 Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Sat, 19 Nov 2022 22:36:54 -0700 Subject: [PATCH] A bit more docs --- docs/index.rst | 7 ++++- docs/installation.rst | 1 + docs/principles.rst | 59 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 docs/principles.rst diff --git a/docs/index.rst b/docs/index.rst index a50c369..9bd09b5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,11 +3,16 @@ Takahē Welcome to the Takahē documentation! Takahē is an ActivityPub server, designed -for low- to medium-size installations, and with the ability to serve multiple +for small- to medium-size installations, and with the ability to serve multiple domains at once. +This documentation is still in development, and will be patchy while Takahē is +in alpha. For more information about Takahē, see +`the official site at jointakahe.org `_. + .. toctree:: :maxdepth: 2 :caption: Contents: installation + principles diff --git a/docs/installation.rst b/docs/installation.rst index 66640be..32a82a4 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -15,6 +15,7 @@ Prerequisites * Something that can run Docker/OCI images * A PostgreSQL 14 (or above) database * One of these to store uploaded images and media: + * Amazon S3 * Google Cloud Storage * Writable local directory (must be accessible by all running copies!) diff --git a/docs/principles.rst b/docs/principles.rst new file mode 100644 index 0000000..737c5f9 --- /dev/null +++ b/docs/principles.rst @@ -0,0 +1,59 @@ +Design Principles +================= + +Takahē is somewhat opinionated in its design goals, which are: + +* Simplicity of maintenance and operation +* Multiple domain support +* Asychronous Python core +* Low-JS user interface + +These are explained more below, but it's important to stress the one thing we +are not aiming for - scalability. + +If we wanted to build a system that could handle hundreds of thousands of +accounts on a single server, it would be built very differently - queues +everywhere as the primary communication mechanism, most likely - but we're +not aiming for that. + +Our final design goal is for around 10,000 users to work well, provided you do +some PostgreSQL optimisation. It's likely the design will work beyond that, +but we're not going to put any specific effort towards it. + +After all, if you want to scale in a federated system, you can always launch +more servers. We'd rather work towards the ability to share moderation and +administration workloads across servers rather than have one giant big one. + + +Simplicity Of Maintenance +------------------------- + +It's important that, when running a social networking server, you have as much +time to focus on moderation and looking after your users as you can, rather +than trying to be an SRE. + +To this end, we use our deliberate design aim of "small to medium size" to try +and keep the infrastructure simple - one set of web servers, one set of task +runners, and a PostgreSQL database. + +The task system (which we call Stator) is not based on a task queue, but on +a state machine per type of object - which have retry logic built in. The +system continually examines every object to see if it can progress its state +by performing an action, which is not quite as *efficient* as using a queue, +but recovers much more easily and doesn't get out of sync. + + +Multiple Domain Support +----------------------- + +TODO + + +Asynchronous Python +------------------- + +TODO + + +Low-JS User Interface +---------------------