164 lines
6.5 KiB
ReStructuredText
164 lines
6.5 KiB
ReStructuredText
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
|
|
* A PostgreSQL 14 (or above) database
|
|
* Hosting/reverse proxy that passes the ``HOST`` header down to Takahē
|
|
* 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 to run *background tasks*, in
|
|
order to fetch profiles, retry delivery of posts, and more.
|
|
|
|
Ideally, you would choose a platform where you can run our worker process in
|
|
the background continuously, but for small installations we have a URL you can
|
|
call periodically instead - see "What To Run", below.
|
|
|
|
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 one copy of the
|
|
`Docker image <https://hub.docker.com/r/jointakahe/takahe>`_ with no extra
|
|
arguments, in order to serve web traffic.
|
|
|
|
The image has required environment variables before it will boot, and this is
|
|
the only way to configure it - see below.
|
|
|
|
You also need to ensure Stator, our background task system, runs regularly.
|
|
You can do this in one of two ways:
|
|
|
|
* Run another copy of image with the arguments ``python manage.py runstator``,
|
|
which will run a background worker continuously.
|
|
|
|
* Call the URL ``/.stator/?token=abc`` periodically (once a minute or more).
|
|
The token value must be the same as you set in ``TAKAHE_STATOR_TOKEN``.
|
|
|
|
The background worker will have a lot more throughput, but you can opt for
|
|
either for a small installation. If Stator gets backed up, you can either
|
|
run more workers or call the URL more often to ensure it gets more throughput.
|
|
|
|
While you can run Takahē directly from a checkout if you like (rather than
|
|
having to use the Docker image), we're not
|
|
officially supporting that right now, as it increases our support burden by
|
|
having to deal with lots of OS and library versions. It's a standard Django
|
|
app, though, so if you know what you're doing, have at it - just expect us to
|
|
push back if you file tickets about things not working on your OS!
|
|
|
|
|
|
Environment Variables
|
|
---------------------
|
|
|
|
All of these variables are *required* for a working installation, and should
|
|
be provided from the first boot.
|
|
|
|
* ``TAKAHE_DATABASE_SERVER`` should be a database DSN for your database (you can use
|
|
the standard ``PGHOST``, ``PGUSER``, etc. variables instead if you want)
|
|
|
|
* ``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 a URI starting with ``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://``, it must be in the form ``gcs://bucket-name``
|
|
(note the two slashes if you just want a bucket name). Your bucket must
|
|
be set to world-readable and have individual object permissions disabled.
|
|
|
|
* If it is set to ``s3://``, it must be in the form
|
|
``s3://access-key:secret-key@endpoint-url/bucket-name``. Your bucket must
|
|
permit publically-readable files to be uploaded.
|
|
|
|
* ``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_SERVER`` should be set to an ``smtp://`` or ``sendgrid://`` URI
|
|
|
|
* If you are using SMTP, it is ``smtp://username:password@host:port/``. You
|
|
can also put ``?tls=true`` or ``?ssl=true`` on the end to enable encryption.
|
|
|
|
* If you are using SendGrid, you should set the URI to ``sendgrid://api-key``
|
|
|
|
* ``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.
|
|
|
|
* If you don't want to run Stator as a background process but as a view,
|
|
set ``TAKAHE_STATOR_TOKEN`` to a random string that you are using to
|
|
protect it; you'll use this when setting up the URL to be called.
|
|
|
|
* If your installation is behind a HTTPS endpoint that is proxying it, set
|
|
``TAKAHE_USE_PROXY_HEADERS`` to ``true``. (The HTTPS proxy header must be called
|
|
``X-Forwarded-Proto``).
|
|
|
|
* If you want to receive emails about internal site errors, set
|
|
``TAKAHE_ERROR_EMAILS`` to a valid JSON list of emails, such as
|
|
``["andrew@aeracode.org"]`` (if you're doing this via shell, be careful
|
|
about escaping!)
|
|
|
|
|
|
Migrations
|
|
----------
|
|
|
|
You will have to run ``manage.py migrate`` when you first install Takahē in
|
|
order to create the database tables; how you do this is up to you. You can
|
|
shell into a running machine, create a one-off task that uses the Docker image,
|
|
or something else.
|
|
|
|
You will also have to run this for minor version releases when new migrations
|
|
are present; the release notes for each release will tell you if one is.
|
|
|
|
|
|
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.
|
|
|
|
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
|
|
---------------
|
|
|
|
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 select the "Domains" link in the sidebar and create one, and then
|
|
you will be able to make your first identity.
|