From 774e91c8a24b85130eb61f2eebf9834ac38fa468 Mon Sep 17 00:00:00 2001
From: Andrew Godwin
Date: Sat, 19 Nov 2022 10:36:51 -0700
Subject: More docs setup

---
 .readthedocs.yaml             | 16 +++++++++++++
 docs/installation.rst         | 55 ++++++++++++++++++++++++++-----------------
 docs/requirements.txt         |  1 +
 requirements.txt              |  1 +
 templates/identity/_menu.html |  6 +++++
 templates/settings/_menu.html |  2 +-
 6 files changed, 58 insertions(+), 23 deletions(-)
 create mode 100644 .readthedocs.yaml
 create mode 100644 docs/requirements.txt

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 &amp; 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
-- 
cgit v1.2.3