How to Set Up Quassel Core on Debian 13 with PostgreSQL and a Web Client
Install Quassel core on Debian 13 with a PostgreSQL backend so your IRC session stays online, then optionally add a browser client behind Apache and backlog search.
Quassel splits an IRC client in two: a core that runs on a server and stays connected to your networks around the clock, and clients that attach to the core from your desktop or phone and replay everything you missed. This guide sets up Quassel core on Debian 13 (Trixie) with PostgreSQL as the storage backend, connects a desktop client, and then adds two optional extras: a browser client behind Apache and a web search over your backlog. The steps also apply to Debian 12; Debian 9 is long out of support.
Requirements
- A Debian 13 server with a user that has
sudorights. A small instance is enough; the core is light. - A DNS name such as
quassel.example.compointing at the server if you want the web client. - The Quassel client installed on your own computer (package
quassel-clienton Debian and Ubuntu, or the installers from quassel-irc.org) or Quasseldroid on Android.
Debian 13 ships Quassel 0.14.0, which is also the latest upstream release.
Step 1: Install Quassel core and PostgreSQL
The core stores its data in SQLite by default. PostgreSQL copes much better with a backlog that grows for years, and the search add-on later in this guide requires it. Install the core, the database server and the Qt PostgreSQL driver:
sudo apt update
sudo apt install quassel-core postgresql libqt5sql5-psqlThe package starts a quasselcore systemd service listening on TCP port 4242. Restart it once so it picks up the newly installed database driver, and check its state:
sudo systemctl restart quasselcore
systemctl status quasselcoreStep 2: Create the database
Open a PostgreSQL shell as the database superuser:
sudo -u postgres psqlCreate a role and a UTF-8 database owned by it, choosing your own password, then quit:
CREATE USER quassel PASSWORD 'choose-a-strong-password';
CREATE DATABASE quassel WITH OWNER quassel ENCODING 'UTF8';
\qStep 3: Open the port and run the first-time wizard
If you use a firewall, allow the core port. With UFW:
sudo ufw allow 4242/tcpStart the Quassel client on your computer and add a core account: your server's hostname or IP, port 4242, and any username and password you like, since no core user exists yet. Keep SSL enabled. The core presents a self-signed certificate on first contact; accept it. Because the core is not configured yet, the client opens the core setup wizard:
- Create the administrator account. This is the core login, not your IRC nickname.
- Select PostgreSQL as the storage backend.
- Enter username
quassel, the password from step 2, hostnamelocalhost, port5432and databasequassel. - Keep the default Database authentication unless you want LDAP.
Run the wizard promptly after installing: until it is completed, whoever connects first becomes the administrator. Afterwards, add your IRC networks and identity in the client as usual. From now on the core stays connected when you close the client.
If the core is already using SQLite
An existing core can be switched over with the --select-backend option, which migrates the data where possible. Stop the service and run the core once by hand as its service user:
sudo systemctl stop quasselcore
sudo -u quasselcore quasselcore --configdir=/var/lib/quassel --select-backend=PostgreSQL
sudo systemctl start quasselcoreMore core users can be added on the server with --add-user in the same way, and passwords reset with --change-userpass=NAME.
Step 4 (optional): Add a web client
The quassel-webserver project is a Node.js application that lets you use your core from a browser. Its README carries a notice that the project is not actively maintained, and the last commit dates from November 2023; treat it as a convenience, keep it behind HTTPS, and prefer the native clients for daily use. It needs Node.js 16 or later; Debian 13 provides version 20.
sudo apt install nodejs npm git apache2Create a service user, fetch the code and install its dependencies:
sudo useradd --system --home-dir /opt/quassel-webserver --shell /usr/sbin/nologin quassel-webserver
sudo git clone https://github.com/magne4000/quassel-webserver.git /opt/quassel-webserver
sudo chown -R quassel-webserver:quassel-webserver /opt/quassel-webserver
cd /opt/quassel-webserver
sudo -H -u quassel-webserver npm install --productionCopy the settings file and edit the copy:
sudo -u quassel-webserver cp settings.cjs settings-user.cjs
sudo nano settings-user.cjsSet the core host in the default block and change the two values at the bottom of the file, so that the page always connects to your own core and is served under /quassel:
host: 'localhost', // inside "default: { ... }"
forcedefault: true,
prefixpath: '/quassel'Create /etc/systemd/system/quassel-webserver.service. The -m http and -l 127.0.0.1 options make it listen on plain HTTP port 64080 on the loopback interface only, so that Apache handles TLS:
[Unit]
Description=Quassel web client
After=network.target quasselcore.service
[Service]
User=quassel-webserver
Group=quassel-webserver
WorkingDirectory=/opt/quassel-webserver
Environment=NODE_ENV=production
ExecStart=/usr/bin/node /opt/quassel-webserver/app.js -l 127.0.0.1 -m http
Restart=always
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now quassel-webserver
systemctl status quassel-webserverProxy it through Apache
Enable the proxy, WebSocket and rewrite modules:
sudo a2enmod proxy proxy_http proxy_wstunnel rewriteCreate /etc/apache2/sites-available/quassel.conf:
<VirtualHost *:80>
ServerName quassel.example.com
DocumentRoot /var/www/html
RedirectMatch ^/$ /quassel
RewriteEngine on
RewriteCond %{HTTP:Connection} Upgrade [NC]
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteRule /quassel/(.*) ws://127.0.0.1:64080/quassel/$1 [P,L]
ProxyPass /quassel http://127.0.0.1:64080/quassel
</VirtualHost>Enable the site, open the web ports and obtain a certificate. You log in to your core through this page, so do not leave it on plain HTTP:
sudo a2ensite quassel
sudo systemctl reload apache2
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo apt install certbot python3-certbot-apache
sudo certbot --apache -d quassel.example.comOpen https://quassel.example.com/ and sign in with your core username and password.
Step 5 (optional): Add backlog search
quassel-rest-search is a small PHP application that searches the core's PostgreSQL database using full-text indexes. It is a hobby project with little recent activity (last commit October 2023), and it changes the core's backlog table, so back up the database first:
sudo -u postgres pg_dump quassel | gzip > ~/quassel-backup.sql.gzInstall PHP for Apache and fetch the code:
sudo apt install libapache2-mod-php php-pgsql
sudo git clone https://github.com/justjanne/quassel-rest-search.git /opt/quassel-rest-searchOpen the database (sudo -u postgres psql quassel) and add the search column, indexes and trigger described in the project's README. The last statement fills the column for existing messages and can run for a long time on a large backlog:
ALTER TABLE backlog ADD COLUMN tsv tsvector;
CREATE INDEX backlog_tsv_idx
ON backlog
USING gin(tsv);
CREATE INDEX backlog_tsv_filtered_idx
ON backlog
USING gin(tsv)
WHERE (type & 23559) > 0;
CREATE TRIGGER tsvectorupdate
BEFORE INSERT OR UPDATE
ON backlog
FOR EACH ROW
EXECUTE PROCEDURE tsvector_update_trigger('tsv', 'pg_catalog.english', 'message');
UPDATE backlog SET messageid = messageid;Create the configuration from the template:
cd /opt/quassel-rest-search
sudo cp qrs_config.default.php qrs_config.php
sudo nano qrs_config.phpSet at least these values and leave the rest as shipped:
define('qrs_db_host', 'localhost');
define('qrs_db_port', 5432);
define('qrs_db_name', 'quassel');
define('qrs_db_user', 'quassel');
define('qrs_db_pass', 'choose-a-strong-password');
define('qrs_backend', 'pgsql-smart');
define('qrs_path_prefix', '/search');The file contains the database password, so restrict it to the web server:
sudo chown root:www-data qrs_config.php
sudo chmod 640 qrs_config.phpAdd the following inside the HTTPS virtual host that Certbot created (/etc/apache2/sites-available/quassel-le-ssl.conf) and reload Apache:
Alias /search /opt/quassel-rest-search
<Directory /opt/quassel-rest-search>
Require all granted
</Directory>sudo systemctl reload apache2The search page at https://quassel.example.com/search asks for your Quassel core login and only shows your own backlog.
Maintenance
- Core and database updates arrive with
sudo apt upgrade. Read the core log withjournalctl -u quasselcore. - Back up the database regularly with the
pg_dumpcommand above; it contains your entire chat history and network settings. - Update the web client with
sudo -H -u quassel-webserver sh -c 'cd /opt/quassel-webserver && git pull && npm prune && npm update', then restart its service. - If the web client becomes slow in busy channels, enable Trim buffer when switching to another buffer in its general configuration; this is the workaround the project documents.
Frequently asked questions
Do I need the web client at all?
No. The core plus a native client (Quassel on desktop, Quasseldroid on Android) is the complete, maintained setup. The web client only adds access from machines where you cannot install anything, at the cost of running a Node.js service that receives few updates.
How do I use a trusted certificate for the core itself?
The core accepts --ssl-cert and --ssl-key options pointing to a certificate and key file, so you can reuse the Let's Encrypt certificate if the core's service user can read the files. Add --require-ssl to refuse unencrypted client connections from other hosts. On Debian, extra options for the service go in /etc/default/quasselcore.
Can several people share one core?
Yes. Each core user has separate networks, identities and backlog. Add users with --add-user as shown in step 3.
What differs on Debian 12?
Nothing in the commands. Debian 12 ships the same Quassel 0.14.0 with older PostgreSQL and Node.js versions, both of which meet the requirements here.