↓Skip to main content

installation #

schist is not yet ready for general use. See the lead section of the readme file for caveats first.

This document will instruct you in building schist from source and performing a traditional installation. This is currently the only way to install schist. (The schist project hopes to provide distribution packages and container images in the future.) An intermediate level of familiarity with Unix system administration is assumed.

You will need the following:

  • A Unix system
  • An internet connection
  • The schist source code (this repository)
  • Rust 1.81 or later (including rustc and cargo; only required transiently)
  • A C toolchain (primarily a linker; only required transiently)
  • PostgreSQL 15 or later
  • nginx
  • certbot

If you have all of these, you can skip to building the server.

dependency notes #

Internet: An internet connection is needed for Cargo to download schist's library dependencies. (cargo vendor can be used to eliminate this requirement, but that is out of the scope of this document.) It is also needed, of course, for users to access the schist server once it is running.

Rust: If your preferred software source does not have a sufficiently recent version of Rust, you can install one using rustup. (Note that rustup can be used to install versions of Rust newer than itself.) If rustup is also not available, see the rustup website for instructions. Rust is only needed during the build steps and can be uninstalled afterwards if you wish.

C toolchain: Rust does not include a linker of its own; it expects the system to have a cc which accepts linking options. Many systems have one installed already; if you do not, look for a package like “build essentials” or “development base”, or install such as GCC or LLVM to obtain a C toolchain.

PostgreSQL: schist assumes its database is PostgreSQL—it is unlikely to work with other SQL implementations.

nginx: schist does not use nginx-specific features—you can substitute another web server if you wish; however, no instructions are yet provided for configuring other web servers.

certbot: certbot is recommended for acquisition and automatic renewal of TLS certificates (issued by Let's Encrypt, a gratis public service). certbot may be available from your system's package manager; if not, check if another ACME client is available, or see the certbot instructions or the list of ACME clients. (If you already have a preferred certificate authority, this item is not applicable.)

schist has many library dependencies, but they will be automatically downloaded and statically linked by Cargo.

building the server binary #

Navigate to the schist source tree. (Relative paths in the remainder of this document are relative to this directory.)

cd /path/to/schist

Execute the build. (This may take several minutes, depending on your system's hardware. You can continue with the next section while the build is running.)

cargo install --path=.

When it is done building, Cargo will copy the server binary to ~/.cargo/bin/schist (hence “cargo install”). Most admins will want to install it to a more conventional location.

sudo cp ~/.cargo/bin/schist /usr/local/bin/

miscellaneous operating system setup #

Create a service account for schist.

sudo useradd --system --home-dir=/var/empty --shell=/sbin/nologin schist

Currently, schist expects a /run/schist directory. It will create a Unix socket in this directory each time it is started, and listen for connections to it. You will need to ensure that the directory exists and is writable to schist (including after reboots). Also ensure that nginx can access its interior.

# /etc/tmpfiles.d/schist.conf
d   /run/schist 0750    schist  nginx   -

installing static files #

The ./static directory contains static files which schist expects the web server to handle requests for. Install them to an appropriate location.

sudo cp -R static /srv/www/schist

configuring the web server #

(If you have not already configured nginx, do so before beginning this section.)

Because schist handles user data, the schist project urges all instance admins to provide transport security and turn on HSTS. (Search engine interactions are especially sensitive—but all applications that exchange user data should use transport encryption. End-to-end encryption is an important part of schist and will be implemented in the future.)

A suitable set of location blocks is provided in ./nginx.schist.conf. You can copy this into the appropriate server block as-is, or use it for reference when writing your own configuration.

configuring the database #

(If you have not already configured PostgreSQL, do so before beginning this section.)

Create a database and a role for schist. This document will assume that they are both named schist, but schist places no requirements on them. Turn on Unix socket authentication for this role. (schist will work with password authentication; however, the password would be supplied in an environment variable, which is not recommended.)

# /var/lib/pgsql/data/pg_hba.conf
local   schist  schist      peer

sudo -u postgres createuser --login schist
sudo -u postgres createdb --owner=schist --encoding=utf8 schist

Initialize the database with schist's schema, provided in ./init.sql.

sudo -u schist psql --dbname=schist --file=init.sql

Write the database information as a libpq connection string make a note of it for the next section.

host=/run/postgresql dbname=schist user=schist

configuring schist #

Currently, schist has very few configuration options, and all of them are passed as environment variables. Environment variables marked “boolean” are interpreted as true if they are set and non-empty. Note that SCHIST_FOO=0 sets a boolean variable to true—use SCHIST_FOO= to set it to false.

  • SCHIST_DATABASE (required): A libpq connection string specifying the database schist should use.

  • SCHIST_LOG_FILE_FILTER, SCHIST_LOG_STDERR, SCHIST_LOG_SYSLOG, SCHIST_LOG_SYSTEMD: Tracing filter strings specifying what to log to each respective destination. auto means off,schist=info (log INFO and more important messages generated directly by schist; log no messages generated by schist's libraries). schist can send log messages to any combination of the four destinations. The default is to log auto to stderr and nothing to other destinations.

  • SCHIST_LOG_FILE_PATH: Specifies what file to write log messages to (see SCHIST_LOG_FILE_FILTER). This file will be appended to if it already exists.

  • SCHIST_OPEN_REGISTRATIONS (boolean): If true, schist will allow anyone to create an account with the sign-up page. This is not recommended unless another method is used to restrict access to the server to trusted users (see the lead section of the readme file).

  • SCHIST_STARTUP_FIFO: If set, schist will open the specified FIFO for writing (creating it if it does not exist), and close it when it has fully started up. This provides a (perhaps crude, but functional) startup notification.

  • SCHIST_SHUTDOWN_FIFO: If set, schist will open the specified FIFO and read from it, terminating when the read completes (or the other end is closed). This similarly provides a way to stop the server (assuming simply sending a SIGTERM is not possible).

starting the schist server #

(If schist is still being built, you will need to wait for it to finish before beginning this section.)

Set the appropriate user ID and the desired environment variables and run the server binary.

sudo -u schist SCHIST_DATABASE="host=/run/postgresql dbname=schist user=schist" SCHIST_LOG_SYSLOG=auto SCHIST_LOG_STDERR=off,schist=error /usr/local/bin/schist

schist runs in the foreground. You can kill the server process with SIGTERM or SIGINT. Most admins will want to run it inside tmux or write an init script to put it into the background.

creating accounts #

Finally, you will want to create one or more accounts. This can be done at any time, whether schist is running or stopped.

Ask for a username or choose a temporary one. Generate a short passphrase and hash it with argon2. Insert these into the accounts table.

sudo -u schist psql --dbname=schist --command="INSERT INTO accounts (id, username, password) VALUES (gen_random_uuid(), 'new_user', '$argon2id$v=19$m=19456,t=2,p=1$5jjpvRxT+WrBZm6kHMuaCQ$+zqS0MCZzhk/O23VGClMFkHTTvjxnzoTIwwCtoI5voc');"

The user can change their username at any time. Remind them to change their password.