diff options
| -rw-r--r-- | .readthedocs.yaml | 16 | ||||
| -rw-r--r-- | docs/installation.rst | 55 | ||||
| -rw-r--r-- | docs/requirements.txt | 1 | ||||
| -rw-r--r-- | requirements.txt | 1 | ||||
| -rw-r--r-- | templates/identity/_menu.html | 6 | ||||
| -rw-r--r-- | templates/settings/_menu.html | 2 |
6 files changed, 58 insertions, 23 deletions
diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..01418e4 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,16 @@ +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/installation.rst b/docs/installation.rst index 3e11f9c..66640be 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -12,13 +12,40 @@ Prerequisites ------------- * SSL support (Takahē *requires* HTTPS) -* Something that can run Docker/OCI images ("serverless" platforms are fine!) +* 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!) +Note that ActivityPub is a chatty protocol that has a lot of background +activity, so you will need a platform that can run *background tasks*, in +order to fetch profiles, retry delivery of posts, and more. + +This means that a "serverless" platform like AWS Lambda or Google Cloud Run is +not enough by itself; while you can use these to serve the web pages if you +like, you will need to run the Stator runner somewhere else as well. + +The flagship Takahē instance, [takahe.social](https://takahe.social), runs +inside of Kubernetes, with one Deployment for the webserver and one for the +Stator runner. + + +What To Run +----------- + +You need to run at least two copies of the Docker image: + +* One with no command or arguments specified, which will serve web traffic +* One with the arguments (command) ``python manage.py runstator``, which will + run the background worker that handles asynchronous communication with other + servers. + +Both of these can have as many copies run as needed. Note that the image has +required environment variables before it will boot, and this is the only way +to configure it - see below. + Environment Variables --------------------- @@ -76,25 +103,6 @@ be provided from the first boot. should get them. -Setting Up Task Runners ------------------------ - -Takahe is designed to not require a continuously-running background worker; -instead, you can trigger the "Stator Runner" (our internal task system) either -via a periodic admin command or via a periodic hit to a URL (which is useful -if you are on "serverless" hosting that does not allow background tasks). - -To use the URL method, configure something to hit -``/.stator/runner/?token=ABCDEF`` every 60 seconds. You can do this less often -if you don't mind delays in content and profiles being fetched, or more often -if you are under increased load. The value of the token should be the same -as what you set for ``TAKAHE_STATOR_TOKEN``. - -Alternatively, you can set up ``python manage.py runstator`` to run in the -Docker image with the same time interval. We still recommend setting -``TAKAHE_STATOR_TOKEN`` in this case so nobody else can trigger it from a URL. - - Making An Admin Account ----------------------- @@ -109,6 +117,9 @@ If your email settings have a problem and you don't get the email, don't worry; fix them and then follow the "reset my password" flow on the login screen, and you'll get another password reset email that you can use. +If you have shell access to the Docker image and would rather use that, you +can run ``python3 manage.py createsuperuser`` instead and follow the prompts. + Adding A Domain --------------- @@ -116,5 +127,5 @@ Adding A Domain When you login you'll be greeted with the "make an identity" screen, but you won't be able to as you will have no domains yet. -You should navigate directly to ``/admin/domains/`` and make one, and then -you will be able to create an identity. +You should select the "Domains" link in the sidebar and create one, and then +you will be able to make your first identity. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..21ef954 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1 @@ +sphinx~=5.3.0 diff --git a/requirements.txt b/requirements.txt index b0eafb7..8eed5d8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -13,3 +13,4 @@ pydantic~=1.10.2 django-htmx~=1.13.0 django-storages[google,boto3]~=1.13.1 whitenoise~=6.2.0 +sphinx~=5.3.0 diff --git a/templates/identity/_menu.html b/templates/identity/_menu.html index f841284..c6c375b 100644 --- a/templates/identity/_menu.html +++ b/templates/identity/_menu.html @@ -8,4 +8,10 @@ <a href="/auth/logout/"> <i class="fa-solid fa-right-from-bracket"></i> Logout </a> + {% if request.user.admin %} + <h3>Administration</h3> + <a href="{% url "admin_domains" %}" {% if section == "domains" %}class="selected"{% endif %}> + <i class="fa-solid fa-globe"></i> Domains + </a> + {% endif %} </nav> diff --git a/templates/settings/_menu.html b/templates/settings/_menu.html index 21bc048..1cccf6b 100644 --- a/templates/settings/_menu.html +++ b/templates/settings/_menu.html @@ -9,7 +9,6 @@ <a href="{% url "settings_follows" %}" {% if section == "follows" %}class="selected"{% endif %}> <i class="fa-solid fa-arrow-right-arrow-left"></i> Follows </a> - {% if request.user.admin %} <h3>Account</h3> <a href="{% url "settings_security" %}" {% if section == "security" %}class="selected"{% endif %}> <i class="fa-solid fa-key"></i> Login & Security @@ -17,6 +16,7 @@ <a href="/auth/logout/"> <i class="fa-solid fa-right-from-bracket"></i> Logout </a> + {% if request.user.admin %} <h3>Administration</h3> <a href="{% url "admin_basic" %}" {% if section == "basic" %}class="selected"{% endif %}> <i class="fa-solid fa-book"></i> Basic |