Stable release

v0.9.6aHandshake

Released 2026-09-16, 23.4 MB.

Notices

Behaviour that changed underneath you. Nothing to run, but worth reading before you update.

  • warningNode 22 or later is now required and Node 26 is the tested target. better-sqlite3 v13 is the first release built on N-API, and its engines range sets the floor. nvm is the recommended way to manage this.
  • warningnpm 12, which ships with Node 26, will not run dependency install scripts unless the package is allowlisted. package.json approves bcrypt, node-pty, @serialport/bindings-cpp and better-sqlite3, pinned to version. Without the allowlist, password hashing, door games and DOS doors over socat fail at runtime rather than at install time.
  • warningallow_netmail_relay is deprecated and ignored. Relay is now netmail_relay_mode, taking off, nodelist or on, and every upgrade lands on nodelist regardless of what the old boolean said. Read docs/sysop/NETMAIL_RELAY.md before choosing on, which is considerably broader than it reads.
  • infoUpgrading the host OS: read docs/sysop/OS_UPGRADE.md first. An Ubuntu release upgrade installs a new PostgreSQL major but does not migrate the data, and can silently remove build-essential.

Upgrade steps

Automatic steps are run by the update tool. Manual ones are yours, and the command is here.

  • Split legacy full-string MSGIDs into the msg_id / msg_orig_addr columnsmanual
    node src/tools/maintenance.js --fix-msgids
  • Re-register the pm2 apps so the pinned child interpreter takes effectmanual
    pm2 delete all && pm2 start ecosystem.config.cjs && pm2 save
  • Route the systemd unit through the Node-resolving wrapper instead of a baked-in Node pathmanual
    install -m 755 setup/canectic-pm2.sh ~/.local/bin/canectic-pm2
  • Check whether the database is SQL_ASCII and convert it to UTF8manual
    setup/convert_db_encoding.sh --preflight-only

Canectic BBS v0.9.6a

A first-class install and update system, professional-grade networking, automated system maintenance, and dynamic call flows.

This is a massive update that moves the system toward a production-ready state. While there are hundreds of small fixes, the general theme is about giving sysops absolute control over their networking and automation while removing the manual pain of system maintenance.

Highlights

A First-Class Install and Update System

Canectic now installs and updates itself. A new sysop runs a single bootstrap script, which resolves the current release, verifies its checksum before unpacking anything, and hands off to that release's own installer to create the directory structure, write .env, set up the database and start the processes. There is no git clone and no source directory left behind to look after.

Updating happens from inside the BBS. A new page at /admin/update shows which release is available, exactly what applying it would do to your installation, and how many users are connected right now. From a shell the same job is node src/tools/update.js --handoff, which stages the release and then hands over to the new version's updater, so the work survives the board being stopped and a release can ship a fixed updater that takes effect for that upgrade rather than the next one. Either route stops the processes, replaces the files, installs dependencies, backs up the database, migrates it, runs the release's declared upgrade steps and starts everything again, recording each phase as it goes so you can see what happened when you come back to it.

Your own work is protected by category rather than by guesswork. Every release ships a manifest of content hashes, so the system can tell a configuration file you have edited from one that is merely out of date. Custom art, public/css/custom.css, door icons and anything you have changed under config/ are kept, and the update tells you which of your files it left alone instead of quietly overwriting them.

Releases can also travel over FTN. Subscribe a file area to CANECTIC_FILES for stable builds or CANECTIC_DEV for development ones, and a new file arriving there is all the update check needs, so a board with an FTN link never has to make an outbound HTTP request at all. The daily check is opt-in and off by default, and only ever raises a notification: it never downloads or applies anything by itself.

Dynamic System Logic and Automation

We have moved away from hardcoded configurations toward a fully dynamic system. The new Call Flow Editor replaces old arrays with a database-backed system, allowing you to design, reorder, and manage call pools and stages directly through the admin UI.

Complementing this is the new Timed Events system. Sysops can now schedule native shell commands or headless Dosemu tasks for recurring chores like backups and door maintenance using a proper cron-style scheduler with output capture and timeout enforcement.

Network Coordination and Netmail Relay

Netmail relay has been completely overhauled to prevent the system from becoming an open relay. The new "nodelist" mode ensures that relay only happens when both ends are listed in the same network nodelist. To make this transparent, a detailed relay log and a dedicated admin page now track exactly why messages were accepted or refused.

For those managing larger networks, the Network Coordinator is a significant addition. It supports the management of network segments and roles (Hubs, NCs, RCs, and ZCs) with automated nodelist generation and distribution. Additionally, a "Bad Echomail" holding area now stores messages for unknown areatags for recovery rather than letting them be silently lost.

Message Migration and Retention

Migrating from other software is now easier with the addition of JAM message base import support, which sits alongside existing SMB support. To keep boards tidy, we have added optional retention limits based on message age or total count. These are enforced by a new daily maintenance job that handles pruning automatically.

Threading has also been unified across FTN, QWK, and NNTP. All paths now use a shared model that guarantees every message belongs to a thread, resolving long-standing issues where replies arrived before their parents.

User Engagement and Templates

We have introduced a sophisticated Message Template system to automate user engagement. Sysops can now trigger custom messages based on lifecycle events, such as registration, birthdays, or login anniversaries. These templates support variable substitution and can be delivered via PM, email, or netmail.

Modern Access and the REST API

Canectic has stepped into the modern era with the REST API v1. Using Bearer tokens, scripted clients and QWK readers can now interact with the system programmatically. The first endpoints provide streamlined access for downloading QWK packets and uploading REP packets.

Stability, Health and Security

To eliminate "silent failures," the background worker now publishes a heartbeat monitored by a new watchdog in the gateway. If the worker crashes or hangs, the watchdog can automatically restart the process.

Security has been tightened with honeypot login detection. Attempts to log in using common targets like "root" or "admin" are flagged and integrated with fail2ban to block offending IPs. We have also added proper reverse proxy support, ensuring client IPs are resolved correctly when running behind Nginx or Caddy.

Admin Tooling Improvements

The admin panel has received a major quality-of-life boost:

  • Batch Subscription: New tools for echolists and filebones allow you to subscribe to hundreds of areas in a few clicks.
  • Combined Area Browser: A single, searchable page now allows you to manage both messages and files.
  • Configuration Reload: A new "Reload" button on the config page allows .env changes to be applied without a full system restart.

Notable Fixes

This release closes 127 bugs. The full list is in docs/sysop/CHANGELOG.md; these are the ones most likely to have been affecting a running board without announcing themselves.

  • Hubs were suppressing nearly all forwarded echomail. A check meant to stop a message going back where it came from was matching almost everything that arrived. On the system that reported it, 127 of 129 candidate messages were held back and the only mail leaving the board was what the sysop had typed. Mail that arrived during a message base import could also be skipped permanently.
  • The worker could stop processing jobs while still reporting as healthy. A stuck job held every concurrency slot, so tossing stopped and nothing said so. Jobs now time out and the gateway watches the worker.
  • Relayed netmail carried the wrong origin, sending replies back to the wrong system, and wrote no Via line, so two systems routing to each other would pass the same message back and forth indefinitely.
  • Editing .env and restarting had no effect, silently, on any installation managed by pm2. The file is now read from disk, disagreements are reported, and changes can be applied without a restart.
  • An upgraded install reported whatever version it was first installed at, including in the origin line on every message it posted. The mailer separately announced version 0.1 to every peer it has ever called.
  • File areas could not be created or edited through the web at all. The form opened, every field worked, and there was nothing to save with.
  • A message with an impossible date pinned its area to the top of the recently-active list permanently and was never pruned. Dates that cannot be true are now rejected on import.
  • setup/install.sh's update mode deleted everything sysop-added under public/, including custom CSS and door icons. It now refuses to update and points at update.sh.
  • /admin/config reported almost every setting as configured by you when it was sitting at the shipped default.

Installing

What you need first

sudo apt install build-essential python3 postgresql redis-server zip unzip gnupg
sudo npm install -g pm2

Node 22 or later, with 26 as the tested target. nvm is the recommended way to manage it, so that an OS upgrade cannot change the runtime under your board. lrzsz is optional, a legacy fallback for ZMODEM now that the native engines are used by default.

DOS door games need two more packages, and dosemu2 is not in the Ubuntu archive:

sudo add-apt-repository ppa:dosemu2/ppa
sudo apt update
sudo apt install dosemu2 socat

socat is the one that is easy to miss. The DosemuPty launch type, which is the recommended one for interactive DOS doors, gives the door a serial port to talk to the caller over, and socat is what creates the pseudo-terminal pair. Without it that launch type cannot allocate a port and the door fails when a caller runs it.

If your database is remote or managed rather than on the same machine, install postgresql-client as well. That is where pg_dump comes from, and pg_dump is what an update uses to back the database up immediately before migrating it.

The installer checks for all of these and names any that are missing, with what each one would have enabled and the command to install it. None of them stop an install, because none of them are needed to run a board: that is exactly why each one is otherwise discovered at the moment a caller first uses the feature it belongs to.

The database

Canectic needs a PostgreSQL role and a database owned by it, and it will not create them behind your back. There are two ways round, depending on whether you can sudo to the postgres user.

Pass --create-database to the installer and it runs setup/create_pg_db_user.sh from the release, which prompts for a name, user and password and creates both with the right encoding. Or create them yourself first:

CREATE USER canectic WITH PASSWORD 'your_password_here';
CREATE DATABASE canectic_bbs OWNER canectic
  TEMPLATE template0 ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C';

The ENCODING clause is not optional. Without it the database inherits its encoding from template1, and on a cluster whose initdb ran under a C or POSIX locale that means SQL_ASCII, which performs no validation at all: invalid byte sequences are stored silently and handed back unchanged. Message bodies carry CP437 art and accented names, so this corrupts data rather than raising an error.

The installer checks that PostgreSQL is accepting connections before it writes anything, so a missing database stops the install at the first step rather than after every file is already on disk.

Installing in one go

curl -fsSLO https://canectic.tranqsoft.com/releases/bootstrap.sh
curl -fsSLO https://canectic.tranqsoft.com/releases/bootstrap.sh.sha256
sha256sum -c bootstrap.sh.sha256 && bash bootstrap.sh --target /opt/canectic --create-database

The bootstrap resolves the current release, checks it against its published checksum before unpacking anything, and hands off to that release's own installer. Verifying the bootstrap first costs two extra lines and is the recommended path; piping it straight into a shell works as well.

This release is the first signed one. Import the key and the bootstrap checks the signature as well as the checksum, and every release after this one is checked against the same key:

curl -fsSLO https://canectic.tranqsoft.com/releases/canectic-release.asc
gpg --import canectic-release.asc
F3F1 6D36 59AF 25FB F947  4C6D B5D8 AB14 3016 761F

Compare that fingerprint before trusting the key. It is the durable name for the release identity: it does not change if the release host moves, and it is what an installed board pins so later releases can be checked without fetching anything. Nothing is refused for being unsigned yet, so a board without the key keeps working exactly as before.

The installer asks where to put things and for your database credentials, writes .env with them at mode 600, creates the directory structure, installs dependencies, builds the schema and starts the processes. Drop --create-database if you created the role and database yourself.

Installing step by step

The documentation and the setup scripts live inside the release, so if you would rather read before you commit, unpack it first and stop:

bash bootstrap.sh --extract-only ~/canectic-0.9.6a
cd ~/canectic-0.9.6a
less docs/sysop/INSTALL.md
bash setup/create_pg_db_user.sh
node src/tools/install.js --target /opt/canectic

That fetches and verifies exactly the same release and runs exactly the same installer; it simply hands you the tree in between. --download-only stops one step earlier and leaves you the archive itself, if you want to check it over before unpacking.

docs/sysop/INSTALL.md covers the rest, including creating your sysop account and verifying the result. It is also published beside bootstrap.sh on the release host, so you can read it without downloading anything.

Upgrading from v0.9.5a

This upgrade still follows the old procedure: pull the source, run update.sh against your run directory, then finish the job by hand. That is unavoidable, because the machinery that replaces it only exists once you are on 0.9.6a. It is the last release that will ask this of you.

cd /path/to/canectic-source
git pull
bash setup/update.sh /path/to/run-directory
cd /path/to/run-directory
npm install --omit=dev
node src/tools/dbmigrations.js
pm2 delete all && pm2 start ecosystem.config.cjs && pm2 save

update.sh overlays the public/ directory, so your custom CSS, door icons and branding survive. Do not use install.sh: it now refuses to touch an existing installation, for reasons described under Notable Fixes.

pm2 delete all is required, not pm2 restart. The four apps now pin their interpreter when the config is evaluated, and pm2 resurrect replays the old saved settings and will not pick that up. A restart leaves the board running on whichever Node was current when you last saved, with no error to tell you.

Several other steps are needed depending on your setup. Each is described in full in docs/sysop/CHANGELOG.md under Upgrade Notes; they are listed here because most of them fail silently when missed.

  • Node 22 or later is now required, and Node 26 is the tested target. nvm is the recommended way to manage it.
  • npm 12 refuses to run dependency install scripts unless the package is allowlisted. package.json now handles this, but a plain npm install on Node 26 without it leaves password hashing, door games and DOS doors broken at runtime rather than failing at install time.
  • allow_netmail_relay is deprecated and ignored. Every upgrade lands on netmail_relay_mode=nodelist regardless of what the old setting said. Read docs/sysop/NETMAIL_RELAY.md before choosing on.
  • If you boot via systemd, install setup/canectic-pm2.sh outside the repository and point the unit at it, or the service stays pinned to whichever Node was current when the unit was generated.
  • A database created before this release may be SQL_ASCII, which stores invalid byte sequences without complaint and hands them back unchanged. That matters for CP437 art and accented names. setup/convert_db_encoding.sh --preflight-only tells you whether you are affected.
  • If your message base predates the MSGID tuple split, run node src/tools/maintenance.js --fix-msgids once. It no longer runs during migrations because it scanned every message table on every update.
  • Upgrading the host OS? Read docs/sysop/OS_UPGRADE.md first. An Ubuntu release upgrade installs a new PostgreSQL major without migrating your data into it.

Future Updates

From here on there is no source tree and no list of steps to remember. An update is either a button or a single command.

On the web, /admin/update shows which release is available, what applying it would do to your installation, and how many users are connected. Press the button and it does the rest. The page will go away while the board restarts; come back to it afterwards and it reports what happened.

From a shell:

node src/tools/update.js --handoff
node src/tools/update.js --status

The first stages the release and hands over to the new version's updater, detached, so the work survives the board being stopped. The second reads back what that run did, and keeps working long after the process that started it has been replaced by it.

Everything an update displaces is copied aside before anything is touched, and a failure before the database has been migrated puts your files back automatically. After that point it stops and tells you where the backup and the database dump are, rather than deciding for you.

To be told when a release exists, turn on update_check_enabled in Admin > Config and choose a channel. The check runs once a day, never downloads anything and never applies anything; it raises a notification and stops. Boards with an FTN link can set update_check_transport to ftn and point update_stable_file_area at the file area carrying the release echo, in which case no outbound connection is made at all.

One thing to expect the first time: the update will report every configuration file you have edited as kept rather than replaced. An installation that came from a source tree carries no manifest to compare against, so it errs toward keeping your version of anything it cannot verify. The update after that one knows the difference.

Testing

3,831 tests passing at this release, up from 1,649 at v0.9.5a.

License

MIT

Version
0.9.6a
Channel
Stable
Node
22.0.0 or later
Upgrades from
0.9.0a or later
Migrations
0001-menu-layout0002-msgid-tuple-split0003-qwk-conference-blocks0004-settings-provenance0005-refresh-stale-version
SHA-256
11b9bb4c6f8687aa411b06a508d8b8074668072ed16319b3d2b722db070cac2e
Files
metadata·manifest