kittehlist docutementation

Installation

kittehlist is not currently available in any package manager. You will need to build it from source.

Installing from source

1. Check out the repo:

git clone https://codeberg.org/annaaurora/kittehlist.git

2. Install the required prerequisites as specified in the README.
   • just is strongly recommended. In the following we will refer to the justfile recipes provided; if you don’t have just, you can instead copy and paste the commands from the justfile into your terminal.
3. Build the frontend with either just build-frontend or just build-release-frontend. (The latter requires minify.)
4. Build the backend with either just build-release (release build, recommended) or cargo build (debug build).
5. Copy the artifacts to appropriate places:
   • The backend binary is at target/release/kittehlist_server (release build) or target/debug/kittehlist_server (debug build)
   • The frontend files are at target/frontend (both debug and release builds).

The development guide provides more details for most of these steps.

Setup

To set up the server, you need:

1. A PostgreSQL database to connect to
2. A config file pointing at the server and frontend files
3. A reverse proxy
4. A service file for your init system

Database

Create a PostgreSQL database for kittehlist, along with a user that has full ownership of the database. We strongly recommend the user’s permissions to be limited to this database only. See the PostgreSQL documentation on CREATE USER and CREATE DATABASE for details. For peer authentication, you may of course create a user with the same name as the user that the kittehlist server itself runs as.

No further database setup is required, kittehlist performs all setup automatically on first startup.

Config

Create a config file and point the server at it via the --config command-line argument.

The config file controls all of kittehlist’s configurable options, including the database connection and the location of the frontend files. The file format is kdl, a format similar to nginx or Caddy config files. We auto-generate full documentation of all config options, which you can read here.

Reverse proxy

We strongly recommend putting kittehlist behind a reverse proxy for TLS. Integrated TLS in kittehlist will not be supported. Additionally, you can use the reverse proxy to directly serve frontend files, increasing performance.

The reverse proxy should forward all paths to kittehlist by default. Kittehlist does not currently accept any standard proxy headers (e.g. X-Forwarded-For), but this may change in the future.

nginx

# kittehlist Nginx config file.
# If you run the reverse proxy on the same host as kittehlist using the default config,
# you only have to adjust the listening options and configure TLS correctly.
#
# This file is part of kittehlist <https://codeberg.org/annaaurora/kittehlist>
# SPDX-License-Identifier: MIT OR Apache-2.0

server {
	# Not recommended
	#listen [::]:80;

	# For TLS, strongly recommended
	listen [::]:443 ssl;
	listen 443 ssl;
	# For HTTP/3, strongly recommended
	http3 on;
	http3_hq on;
	quic_retry on;
	listen [::]:443 quic reuseport;
	listen 443 quic reuseport;

	# Set the domain name under which kittehlist is served.
	server_name kittehlist.invalid;

	# Add your TLS certificate configuration here.

	location / {
		# Adjust host and port as required.
		proxy_pass http://localhost:8062/;

		# These configuration options are required for WebSockets to work.
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "upgrade";

		proxy_redirect off;
		proxy_set_header Host $host:$server_port;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Host $server_name;
		proxy_set_header X-Forwarded-Proto $scheme;
	}
}

Service file

The kittehlist server is a standard self-contained binary that will keep running forever. No external task jobs or similar are required. Obviously, the server must start after the database is ready to accept connections.

If you want to run kittehlist as a non-root user (strongly recommended), and you can’t use a dynamic user (required for postgres peer auth), you should use a non-privileged kittehlist user (without login capabilities or basically any permissions).

systemd

Note that we use (most of) the applicable security lockdown features to restrict the kittehlist process as much as possible.

# kittehlist server systemd service.
# This service configuration is designed for kittehlist’s default config.
#
# This file is part of kittehlist <https://codeberg.org/annaaurora/kittehlist>
# SPDX-License-Identifier: MIT OR Apache-2.0

[Unit]
Description=Kittehlist server
# Omit these two if it is not a dependency for your configuration.
Requires=network.target
After=network.target

[Service]
# Alternatively, use DynamicUser, but that will make PostgreSQL connections more involved
User=kittehlist

WorkingDirectory=/usr/share/kittehlist
SyslogIdentifier=kittehlist
ExecStart=/usr/bin/kittehlist_server --config /etc/kittehlist.kdl
Restart=on-failure

ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectKernelLogs=true
MemoryDenyWriteExecute=true
NoExecPaths=/
ExecPaths=/usr/lib /usr/lib64 /usr/bin/kittehlist_server
ReadWritePaths=/run
CapabilityBoundingSet=
AmbientCapabilities=

[Install]
WantedBy=multi-user.target