muscl/docs/installation.md

Installation and configuration

This document contains instructions for the recommended way of installing and configuring muscl.

Note that there are separate instructions for installing on NixOS and installing with SUID/SGID mode.

Installing with deb on Debian

You can install muscl by adding the PVV apt repository and installing the package:

# Become root (if not already)
sudo -i

# Check the version of your Debian installation
VERSION_CODENAME=$(lsb_release -cs)

# Add the repository
echo "deb [signed-by=/etc/apt/keyrings/pvvgit-projects.asc] https://git.pvv.ntnu.no/api/packages/Projects/debian $VERSION_CODENAME main" | tee -a /etc/apt/sources.list.d/gitea.list

# Pull the repository key
curl https://git.pvv.ntnu.no/api/packages/Projects/debian/repository.key -o /etc/apt/keyrings/pvvgit-projects.asc

# Update package lists
apt update

# Install muscl
apt install muscl

Creating a database user

In order for the daemon to be able to do anything interesting on the mysql server, it needs a database user with sufficient privileges. You can create such a user by running the following commands on the mysql server as the admin user (or another user with sufficient privileges):

CREATE USER `muscl`@`%` IDENTIFIED BY '<strong_password_here>';
GRANT SELECT, INSERT, UPDATE, DELETE ON `mysql`.* TO `muscl`@`%`;
GRANT GRANT OPTION, CREATE, DROP ON *.* TO 'muscl'@'%';
FLUSH PRIVILEGES;

Now you should add the login credentials to the muscl configuration file, typically located at /etc/muscl/config.toml.

Setting the myscl password with systemd-creds

The debian package assumes that you will provide the password for muscl's database user with systemd-creds.

You can add the password like this:

# Become root (if not already)
sudo -i

# Unless you already have a working credential store, you need to set it up first
mkdir -p /etc/credstore.encrypted
systemd-creds setup

# Be careful not to leave the password in your shell history!
# Add a space before setting the next line to avoid this.
 export MUSCL_MYSQL_PASSWORD="<strong_password_here>"

# Now set the muscl mysql password
systemd-creds encrypt --name=muscl_mysql_password <(echo "$MUSCL_MYSQL_PASSWORD") /etc/credstore.encrypted/muscl_mysql_password

If you are running systemd older than version 254 (see systemctl --version), you might have to override the service to point to the path of the credential manually, because ImportCredential= is not supported. Run systemctl edit muscl.service and add the following lines:

[Service]
LoadCredentialEncrypted=muscl_mysql_password:/etc/credstore.encrypted/muscl_mysql_password

A note on minimum version requirements

The muscl server will work with older versions of systemd, but the recommended version is 254 or newer.

For full landlock support (disabled by default), you need a linux kernel version 6.7 or newer.