Add shared installation documentation

1 files changed, 162 insertions, 0 deletions

diff --git a/installation.md b/installation.md
new file mode 100644
index 0000000..f0b37bd
--- /dev/null
+++ b/installation.md
@@ -0,0 +1,162 @@
+Installation of sr.ht web services uses a mostly consistent procedure across the
+network. Specific details to each service are available on each service's
+installation page:
+
+- [build.sr.ht](/builds.sr.ht/installation.md)
+- [git.sr.ht](/git.sr.ht/installation.md)
+- [man.sr.ht](/man.sr.ht/installation.md)
+- [meta.sr.ht](/meta.sr.ht/installation.md)
+- [todo.sr.ht](/todo.sr.ht/installation.md)
+
+General installation instructions follow.
+
+# Packages
+
+sr.ht provides a number of Linux distribution package repositories for your
+use. For details specific to your distribution, see [packages.md](/packages.md).
+Even if you wish to install sr.ht services from source, your distribution may
+not include some of our dependencies and using our package repositories is
+recommended.
+
+Installation from packages will also give you distro-specific daemon services
+and will handle database migrations automatically during system updates.
+
+# Prerequisites
+
+You will need at least:
+
+- A PostgreSQL server
+- A Redis server
+- A mail server
+- A cron daemon
+
+In order to use most sr.ht services.
+
+# sr.ht core
+
+sr.ht core is a Python package that provides shared functionality across all
+sr.ht services. It also contains the default templates and stylesheets that give
+sr.ht a consistent look and feel.
+
+The core package is listed as a dependency of the official `*.sr.ht` packages,
+so installing it explicitly is not necessary if you are using our package
+repositories. If you are not using our packages, obtain the [source
+code](https://git.sr.ht/~sircmpwn/srht) and install it like a typical Python
+package (`./setup.py install --prefix=/usr`). You will need to install its
+dependencies beforehand, for an up-to-date list see [the
+package](https://git.sr.ht/~sircmpwn/sr.ht-pkgbuilds/tree/python-srht/PKGBUILD).
+
+# Package Installation
+
+Packages are named as you would expect: meta.sr.ht is called `meta.sr.ht`. On
+package managers where dots are not permitted in package names, dashes are used.
+Underscores are used on systems where dashes are not permitted.
+
+If installing from source, see [the
+packages](https://git.sr.ht/~sircmpwn/sr.ht-pkgbuilds) for an up-to-date list of
+dependencies and install it like any other Python package: `./setup.py install
+--prefix=/usr`. When installing from source, daemon service files are not
+provided; you must write one appropriate to your system.
+
+# Site Configuration
+
+Each site will search for its config file in two locations: `./config.ini` and
+`/etc/sr.ht/subdomain.ini` (for example, meta.sr.ht looks for
+`/etc/sr.ht/meta.ini`). The exact nature of this config file varies depending on
+which service you're setting up - from source, see `config.ini.example` and from
+packages see `/etc/sr.ht/subdomain.ini.example`.
+
+# Database Configuration
+
+Start by setting your config.ini's connection string to a superuser, then run
+the following commands to create the initial schema:
+
+    $ python3
+    >>> from [module].app import db
+    >>> db.create()
+
+Substitute `[module]` for the specific application's module, such as `metasrht`
+or `buildsrht`. When complete, you may update your connection string to use a
+less privileged user.
+
+## Schema Upgrades
+
+We use [alembic](http://alembic.zzzcomputing.com/en/latest/) to manage schema
+migrations. A sample `alembic.ini` is provided (`alembic.ini.example` from
+source and `/etc/sr.ht/alembic/subdomain.ini.example` from packages), which you
+should modify to suit your needs - you will probably only need to set the
+connection string.
+
+Run `alembic stamp head` once to tell alembic the schema is up-to-date. Future
+upgrades will be managed automatically by the package, or if you're using the
+source code you can run `alembic upgrade head` when you pull the latest version
+down.
+
+# Compile static assets
+
+This step is only necessary for users configuring sr.ht from source. Run `make`
+in the root of the repository to compile static assets.
+
+# Start the service
+
+A service file is included in the packages and uses the same name as the
+package. On Arch Linux, for example, you can run `systemctl enable --now
+meta.sr.ht` to start up meta.sr.ht, or `rc-update add meta.sr.ht && service
+meta.sr.ht start` on Alpine. The service will be running at the port specified
+in its config file, and you must now prepare to proxy to it.
+
+# Proxy configuration
+
+The exact nginx configuration you use will vary depending on your needs. Here is
+an example for meta.sr.ht:
+
+    server {
+        listen 80;
+        server_name meta.sr.ht;
+
+        location / {
+            return 302 https://$server_name$request_uri;
+        }
+
+        location ^~ /.well-known {
+            root /var/www;
+        }
+    }
+
+    server {
+        listen 443 ssl;
+        listen [::]:443 ssl;
+        server_name meta.sr.ht;
+        client_max_body_size 100M;
+        ssl_certificate /var/lib/acme/live/meta.sr.ht/fullchain;
+        ssl_certificate_key /var/lib/acme/live/meta.sr.ht/privkey;
+        ssl_trusted_certificate /var/lib/acme/live/meta.sr.ht/fullchain;
+
+        location / {
+            proxy_pass http://127.0.0.1:5002;
+        }
+
+        location /static {
+            root /usr/lib/python3.6/site-packages/metasrht;
+        }
+
+        location ^~ /.well-known {
+            root /var/www;
+        }
+    }
+
+Once the proxy is configured, you should be able to log into your new service.
+
+# Hacking on sr.ht
+
+If you just want to get the codebase running to hack on it, follow these steps:
+
+1. [Prerequisites](#prerequisites)
+2. [sr.ht core](#sr.ht-core), however, you can simply clone it somewhere and add
+   it to your Python path. Also export `SRHT_PATH=/path/to/sr.ht-core` to use
+   your development repository for generating static assets.
+3. [Site configuration](#site-configuration), but you can just put `config.ini`
+   in the working directory and sr.ht will read it there.
+4. [Database configuration](#database-configuration)
+5. [Compile static assets](#compile-static-assets)
+6. `./run.py` will start the development server.