{"id":22547188,"url":"https://github.com/digitalcircuit/salt-box-quassel","last_synced_at":"2025-07-17T18:32:46.644Z","repository":{"id":83015880,"uuid":"78157569","full_name":"digitalcircuit/salt-box-quassel","owner":"digitalcircuit","description":"Full Quassel IRC setup in a box, via SaltStack configuration management","archived":false,"fork":false,"pushed_at":"2025-05-14T04:51:25.000Z","size":1530,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-14T06:09:44.687Z","etag":null,"topics":["quassel","quassel-client","quassel-webserver","salt"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalcircuit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-05T23:48:27.000Z","updated_at":"2025-05-14T04:51:28.000Z","dependencies_parsed_at":"2023-11-08T05:43:34.569Z","dependency_job_id":"fb2206d2-2ef6-4ac7-a62e-134b96466777","html_url":"https://github.com/digitalcircuit/salt-box-quassel","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/digitalcircuit/salt-box-quassel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalcircuit%2Fsalt-box-quassel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalcircuit%2Fsalt-box-quassel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalcircuit%2Fsalt-box-quassel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalcircuit%2Fsalt-box-quassel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalcircuit","download_url":"https://codeload.github.com/digitalcircuit/salt-box-quassel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalcircuit%2Fsalt-box-quassel/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265645428,"owners_count":23804185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["quassel","quassel-client","quassel-webserver","salt"],"created_at":"2024-12-07T15:10:44.460Z","updated_at":"2025-07-17T18:32:46.636Z","avatar_url":"https://github.com/digitalcircuit.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"Quassel-in-a-box\n===============\n\nThis takes a stock Ubuntu 22.04/24.04 system, and with Salt, turns it into an IRC setup with desktop, mobile, and web clients, search, a home page, and includes Let's Encrypt certificates for encrypted connections.\n\n*This is not endorsed by the official [Quassel IRC project][web-quassel], [Quassel Webserver][web-quassel-web], or [Quassel Rest Search][web-quassel-rest-search]*\n\n***Work in progress:** features may change without warning.  Please read the commit log before updating production systems.*\n\n## Deployment\n\n* Customize the files in ```pillar``` to suit your environment\n  * See below for the minimum viable setup (e.g. local development)\n* Apply the salt state via ```salt-call```\n  * Works with a [masterless minion Salt setup](https://docs.saltstack.com/en/latest/topics/tutorials/quickstart.html ), no need for master\n\n### Minimum viable setup (local development)\n\n1. Set your server hostname\n\n[`pillar/server/hostnames.sls`](pillar/server/hostnames.sls):\n```yaml\n# Hostname details (optional/default configuration removed)\nserver:\n  # Hostnames\n  hostnames:\n    # Domains by certificate chain\n    # Main domain\n    cert-primary:\n      # Hostname visible to the world, used in SSL certs and branding\n      root: public.domain.here.example.com\n```\n\n2. Set up `certbot` for Let's Encrypt certificates, or disable it\n\n[`pillar/server/web/certbot.sls`](pillar/server/web/certbot.sls):\n```yaml\n# Certificate details for Let's Encrypt (optional/default configuration removed)\ncertbot:\n  # Replace dummy certificates with certificates from Let's Encrypt?\n  #\n  # NOTE - enabling certbot implies you agree to the Let's Encrypt\n  # Terms of Service (subscriber agreement).  Please read it first.\n  # https://letsencrypt.org/repository/#let-s-encrypt-subscriber-agreement\n  enable: True\n  # Use staging/test server to avoid rate-limit issues?\n  testing: False\n  # Account details\n  account:\n    # Email address for recovery\n    email: real-email-address@example.com\n```\n\n3. Set initial credentials for Quassel core\n\n[`pillar/server/chat/quassel/main.sls`](pillar/server/chat/quassel/main.sls):\n```yaml\n# Quassel configuration (optional/default configuration removed)\nserver:\n  chat:\n    quassel:\n      # Quassel core\n      core:\n        # Initial/administrative user\n        admin:\n          username: initial_quassel_user\n          password: change_this_password\n      # PostgreSQL database setup\n      database:\n        password: also_change_this_database_password\n```\n\n## Usage\n\n### Default setup\n\n* [Quassel IRC][web-quassel] core running on port `4242`, with admin user [as in pillar data](pillar/server/chat/quassel/main.sls)\n  * Stable version configured [from mamarley's PPA](https://launchpad.net/~mamarley/+archive/ubuntu/quassel)\n* Website at [configured server hostname](pillar/server/hostnames.sls), with HTTP/HTTPS enabled\n  * [Quassel Web][web-quassel-web] available at `https://hostname/chat`\n  * [Quassel Rest Search][web-quassel-rest-search] available at `https://hostname/search`\n  * Basic connection information and links to the desktop and [Android client, Quasseldroid](https://quasseldroid.info)\n* Let's Encrypt for certificates with automated deployment and renewal, including reloading services\n* 2 GB swapfile for low-memory systems (e.g. 1 GB RAM)\n  * Initial NPM deploy of Quassel Web spikes memory usage\n\n### Configuration\n\n* Tune PostgreSQL performance (**recommended**)\n  * Modify [`pillar/server/storage/database.sls`](pillar/server/storage/database.sls) according to your system specifications.\n  * Periodic cleanup may help as well, see [the Quassel IRC project wiki for details](https://bugs.quassel-irc.org/projects/1/wiki/PostgreSQL#PostgreSQL-performance-and-maintenance )\n\n* Add new Quassel core user\n```bash\n$ sudo --user=quasselcore quasselcore --add-user --configdir=/var/lib/quassel\n```\n\n* Change password of Quassel core user `USERNAME` without access to original password\n```bash\n$ sudo --user=quasselcore quasselcore --change-userpass=USERNAME --configdir=/var/lib/quassel\n```\n*Administration UI to be added later.*\n\n### Extra features\n\n#### Lock down allowed networks\n* Useful for a shared core provided by a network\n* Not yet recommended for use by fully untrusted users\n  * Work is ongoing in the Quassel IRC upstream project to provide restricted accounts\n\n[`pillar/server/chat/quassel/main.sls`](pillar/server/chat/quassel/main.sls):\n```yaml\n# Quassel configuration\nserver:\n  chat:\n    quassel:\n      # [...existing configuration here...]\n      # Restrictions and lockdown\n      lockdown:\n        # Lock the IRC ident to the Quassel account username\n        strict-ident: False\n        # Limit what networks can be used from any Quassel account\n        strict-networks:\n          # If enabled, only networks listed below are allowed\n          enabled: False\n          # List of allowed IRC networks (domain names and/or IP addresses)\n          #\n          # NOTE - Domain names are translated to IP addresses, refreshed\n          # periodically.  If you make use of round-robin DNS, you will need to\n          # specify all possible domain names/IP addresses.\n          hosts:\n            - \"irc.example.invalid\"\n            - \"server-a.example.invalid\"\n            - \"server-b.example.invalid\"\n          # List of allowed ports for IRC connections\n          ports:\n            - 6667\n            - 6697\n```\n\n#### Manage software versions\n* Modify [`pillar/server/chat/quassel/versions.sls`](pillar/server/chat/quassel/versions.sls)\n  * Recommendation: set a fixed tag/commit ID for production, test newer versions locally first\n\n#### Customize branding, name, help messages, etc on website\n* Modify [`pillar/server/chat/quassel/branding.sls`](pillar/server/chat/quassel/branding.sls)\n\n#### Report system status via Telegraf to a remote metrics server\n* Configure [`pillar/server/metrics.sls`](pillar/server/metrics.sls) with metrics server details\n* Example receiving setup: Grafana + Telegraf HTTP Listener + InfluxDB\n\n#### Set up daily automatic, PGP-encrypted backups\n* Configure [`pillar/common/backup/system.sls`](pillar/common/backup/system.sls) with upload script and encryption settings\n  * Example script given for use with [rclone](https://rclone.org/), enabling backup to many cloud/self-hosted services\n\n## Credits\n\n* [Quassel IRC][web-quassel] for the IRC client and server core\n* [Quassel Webserver][web-quassel-web] for web chat\n* [Quassel Rest Search][web-quassel-rest-search] for web search\n* *Some credits in the individual files, too*\n* *If you're missing, let me know, and I'll fix it as soon as I can!*\n\n[web-quassel]: https://github.com/quassel/quassel\n[web-quassel-rest-search]: https://github.com/justjanne/quassel-rest-search/\n[web-quassel-web]: https://github.com/magne4000/quassel-webserver\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalcircuit%2Fsalt-box-quassel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalcircuit%2Fsalt-box-quassel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalcircuit%2Fsalt-box-quassel/lists"}