takahe/docs/installation.rst

Installation
============

We recommend running using the Docker/OCI image; this contains all of the
necessary dependencies and static file handling preconfigured for you.

All configuration is done via either environment variables, or online through
the web interface.


Prerequisites
-------------

* SSL support (Takahē *requires* HTTPS)
* Something that can run Docker/OCI images ("serverless" platforms are fine!)
* 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!)


Environment Variables
---------------------

All of these variables are *required* for a working installation, and should
be provided from the first boot.

* ``PGHOST``, ``PGPORT``, ``PGUSER``, ``PGDATABASE``, and ``PGPASSWORD`` are the
  standard PostgreSQL environment variables for configuring your database.

* ``TAKAHE_SECRET_KEY`` must be a fixed, random value (it's used for internal
  cryptography). Don't change this unless you want to invalidate all sessions.

* ``TAKAHE_MEDIA_BACKEND`` must be one of ``local``, ``s3`` or ``gcs``.

    * If it is set to ``local``, you must also provide ``TAKAHE_MEDIA_ROOT``,
      the path to the local media directory, and ``TAKAHE_MEDIA_URL``, a
      fully-qualified URL prefix that serves that directory.

    * If it is set to ``gcs``, you must also provide ``TAKAHE_MEDIA_BUCKET``,
      the name of the bucket to store files in. The bucket must be publically
      readable and have "uniform access control" enabled.

    * If it is set to ``s3``, you must also provide ``TAKAHE_MEDIA_BUCKET``,
      the name of the bucket to store files in.

* ``TAKAHE_MAIN_DOMAIN`` should be the domain name (without ``https://``) that
  will be used for default links (such as in emails). It does *not* need to be
  the same as any domain you are hosting user accounts on.

* ``TAKAHE_EMAIL_HOST`` and ``TAKAHE_EMAIL_PORT`` (along with
  ``TAKAHE_EMAIL_USER`` and ``TAKAHE_EMAIL_PASSWORD``, if needed) should point
  to an SMTP server Takahe can use for sending email. Email is *required*, to
  allow account creation and password resets.

  * If you are using SendGrid, you can just set an API key in
    ``TAKAHE_EMAIL_SENDGRID_KEY`` instead.

* ``TAKAHE_EMAIL_FROM`` is the email address that emails from the system will
  appear to come from.

* ``TAKAHE_AUTO_ADMIN_EMAIL`` should be an email address that you would like to
  be automatically promoted to administrator when it signs up. You only need
  this for initial setup, and can unset it after that if you like.

* ``TAKAHE_STATOR_TOKEN`` should be a random string that you are using to
  protect the stator (task runner) endpoint. You'll use this value later.

* If your installation is behind a HTTPS endpoint that is proxying it, set
  ``TAKAHE_SECURE_HEADER`` to the header name used to signify that HTTPS is
  being used (usually ``X-Forwarded-Proto``)

* If you want to receive emails about internal site errors, set
  ``TAKAHE_ERROR_EMAILS`` to a comma-separated list of email addresses that
  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
-----------------------

Once the webserver is up and working, go to the "create account" flow and
create a new account using the email you specified in
``TAKAHE_AUTO_ADMIN_EMAIL``.

Once you set your password using the link emailed to you, you will have an
admin account.

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.


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.