Documentation

Installation guide

Source:INSTALL.md on the release host

All documentation

Canectic BBS: Installation Guide

Prerequisites

Operating System

Canectic BBS runs on Linux. Tested on Debian/Ubuntu-based systems. Other distributions should work with equivalent packages.

System Packages

# Required
sudo apt install build-essential python3 postgresql redis-server zip unzip gnupg

# Recommended
sudo npm install -g pm2        # Process management (or: npm install -g pm2)

zip and unzip are not optional in practice: zip builds outbound QWK and REP packets, and unzip is what unpacks a release when you update. gnupg is what checks the signature on a release.

A local postgresql brings postgresql-client with it, which is where pg_dump comes from. If your database is remote or managed, install the client separately:

sudo apt install postgresql-client

That one matters more than it looks. pg_dump is what an update uses to back the database up immediately before migrating it, which is the thing that makes a failed migration recoverable. Without it an update has to run with --no-dump.

Redis

Canectic requires Redis 6.2 or later. Check what you have with redis-server --version (or redis-cli INFO server for a Redis on another machine). Ubuntu 22.04's redis-server package is 6.0, so on 22.04 install a newer Redis from the Redis project's own packages.

An older server is not refused, and Canectic does run on one, but it is not supported. System Info and the Update page show the Redis version and warn below 6.2, and BullMQ, which runs the job queues, logs a warning about it every time it connects. Below 6.0, which has no RESP3 (the protocol Canectic speaks), Canectic falls back to the older RESP2 protocol and says so in system.log.

Archive formats

Canectic opens ZIP archives itself. Every other format needs a program, and an FTN board meets several: mail bundles packed with ARJ or LHA, FidoNet's nodelist and NODEDIFF as ARC, file echoes and uploads in RAR, ARJ, LHA or 7z.

sudo apt install 7zip nomarch unar
Package Opens
7zip ARJ, LHA, 7z, gzip, bzip2, xz, tar, and ZIPs packed by old PKZIP methods; RAR with 7zip-rar (in multiverse)
nomarch ARC and PAK
unar ZOO, and RAR when 7zip-rar is not installed; Canectic also tries it on any archive the others cannot read

None of them is needed to start the board. Without them, a mail bundle in a format nothing here opens goes to Bad Files with a note saying what to install (Retry unpacks it once you have), and a nodelist, echolist, QWK packet, file description or preview in one is skipped with the same note in the log. System Info lists which formats the board can open and which it cannot. See ARCHIVES.md for the details.

DOS door games

Skip this if you are not running DOS doors. If you are, you need both 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 part 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. The Dosemu console-only type does not need socat, but it is for sysop utilities rather than for doors people call in to play.

Because dosemu2 comes from a PPA rather than the archive, an OS release upgrade disables it and the source has to be re-pointed afterwards. See OS_UPGRADE.md.

Legacy file transfer

sudo apt install lrzsz        # optional

The native XMODEM and ZMODEM engines are used by default and lrzsz is only a fallback for terminals that need one. Nothing breaks without it.

What the installer tells you

The installer checks for all of these and names the ones that are missing, along with what each one would have enabled and the command to install it. None of them stop an install: a board runs without any of them right up until somebody uses the feature that needs one.

Node.js

Node.js 22 or later is required. The project uses ES modules, Express 5, and the --experimental-vm-modules flag for Synchronet JS door shims.

The floor is 22 because better-sqlite3 v13 requires it. That version is worth having: it is the first release built on N-API, so its native binary is stable across Node major versions and ships prebuilt. Earlier releases had to be compiled against each Node version's V8 internals, which is what made installs fail on newer Node and required build-essential and python3 to be present.

nvm install 26
nvm alias default 26

nvm is the recommended way to run Canectic, and the rest of this guide assumes it. A BBS is expected to stay up for years, across several OS upgrades, and nvm decouples the Node version from the distro: you upgrade the OS without the packaged Node moving underneath the BBS, and you upgrade Node without waiting for your distro to ship it. Setting the default alias matters, because that is what the boot path follows.

Note that global npm packages are installed per Node version under nvm. After nvm install of a new major, re-install anything you rely on globally (npm install -g pm2).

Install natively

A distro or NodeSource package works too, and is fully supported. Canectic never hardcodes an interpreter path, so nothing in the tree assumes one layout or the other.

# Debian/Ubuntu, via NodeSource
curl -fsSL https://deb.nodesource.com/setup_26.x | sudo -E bash -
sudo apt install -y nodejs

The trade-off is that the Node version is then tied to your distro packaging, so an OS upgrade can move it without warning. If you go this route, pin the package and check node -v after any OS upgrade.


Quick Start

One command

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

That resolves the newest stable release, downloads it, verifies its checksum before unpacking anything, extracts it, and hands off to that release's own installer. There is no git clone and no source directory to look after afterwards.

Verifying the bootstrap first is two extra lines and it is the recommended path. Piping it straight into a shell works:

curl -fsSL https://canectic.tranqsoft.com/releases/bootstrap.sh | bash -s -- --target /opt/canectic

Checking the signature

Releases are signed, and the bootstrap checks the signature, so it needs gpg (sudo apt install gnupg, in the list above) and stops without it. It accepts a signature only if it was made by a Canectic release key, whose fingerprints are built into the bootstrap. There are two: the active key, which signs releases, and the reserve, kept offline for the day the active one has to be retired:

F3F1 6D36 59AF 25FB F947  4C6D B5D8 AB14 3016 761F   active
DE1A 1F1F E233 5146 64DE  7113 8ABB 2D2E C0D1 3127   reserve

These are the numbers that matter: it does not change if the release host ever moves, and it is what your board starts out trusting, so that later releases can be checked without fetching anything. Your board keeps its own list of trusted release keys in .canectic-trust/ in the installation; see Release keys in docs/sysop/UPDATES.md. The bootstrap prints the one that signed the release when the check passes, so you can compare it with this page.

Before it checks anything, the bootstrap looks the release keys up on a keyserver (keys.openpgp.org), so a key revoked since the bootstrap was written is refused. That needs the internet, which a first install needs anyway for npm install. If the keyserver cannot be reached the bootstrap stops and says so; once you have compared the fingerprint above with what it prints, run it again with --no-keyserver.

You get signature verified (Canectic release key ...) and the whole publish is accounted for: the signature covers the checksum list, the checksum list covers the release metadata, and the metadata covers the archive. A signature that does not match, that was made by any other key, or by a key that has been revoked or has expired, stops the install before anything is unpacked. So does a release with no signature at all.

Your own keyring is never used or changed: the bootstrap checks in a private one of its own.

Installing from the archive alone

A release that arrives down a file echo, or that you copied across by hand, may be just the archive (canectic-0.9.20b.zip, perhaps upper-cased by the echo), with no checksum list or index beside it. Point --from at the directory holding it:

bash bootstrap.sh --from /path/to/the/archives --target /opt/canectic

With no --version it takes the newest stable release there. The archive carries a signed MANIFEST listing every file in it: the bootstrap checks that signature without unpacking anything, then unpacks into a temporary directory and checks every file against the MANIFEST, refusing any file that does not match or that the MANIFEST does not list, before anything from the archive is run. The keyserver is asked as above.

npm install still needs the npm registry, or a mirror you have set in .npmrc (registry=...), since a release ships no node_modules. After that, updates can come over FTN alone: see docs/sysop/UPDATES.md.

Flag Effect
--target DIR Where to install. Asked for if not given (default /opt/canectic)
--channel development Track development builds rather than stable
--version 0.9.12a A specific release
--url BASE A different release host
--from DIR Artifacts already on disk, from a file echo or copied by hand; may be the archive alone
--no-keyserver Do not look the release keys up on a keyserver (compare the fingerprint above yourself)
--keyserver URL A different keyserver
--download-only Fetch and verify, then stop, so you can inspect it
--extract-only DIR Fetch, verify and unpack into DIR, then stop, so you can read the docs and run the setup scripts first
--create-database Also create the PostgreSQL role and database (needs sudo to postgres)
--db-name / --db-user / --db-pass / --db-host Database credentials, instead of being asked
--yes Take the defaults and ask nothing (needs --target)
--no-deps / --no-database / --no-start Leave those to you

Any flag the bootstrap does not know itself is passed through to the release's installer. The bootstrap needs unzip, sha256sum, gpg, Node 22 or later, and curl or wget (for the keyserver, and for the release unless you use --from), and stops at once if one is missing.

The installer asks where to install and for database credentials, writes .env at mode 600, creates the runtime directories, installs dependencies, runs the schema, and starts the processes. Anything it skips it names, with the command you now owe.

It refuses to install over a directory that already holds Canectic, and points you at the updater instead, which knows which of your files to leave alone. See docs/sysop/UPDATING.md.

A withdrawn release is never installed. Left to choose, the bootstrap takes the newest release that has not been withdrawn; asked for one by name, it stops and says why it was withdrawn and what replaces it.

A development build cannot be installed from nothing. It is a delta against a stable release, so install the stable it names first and then update to it.

Doing it by hand

If you would rather not run a script that downloads things, --download-only gets you a verified artifact and stops:

bash bootstrap.sh --download-only
unzip canectic-0.9.12a.zip
cd canectic-0.9.12a
node src/tools/install.js --target /opt/canectic

The installer inside the release is the same one the bootstrap would have run.


Installing from the source repository

The older path, still supported, and what you want if you are working on Canectic itself rather than running it.

1. Get the Source

From a release archive (recommended):

Download the latest release from the Canectic Releases page and extract:

unzip canectic-0.9.12a.zip
cd canectic-0.9.12a

From git (specific release):

git clone --branch v0.9.12a --depth 1 https://gitlab.tranqsoft.com/drog007/canectic.git
cd canectic

From git (latest development):

git clone https://gitlab.tranqsoft.com/drog007/canectic.git
cd canectic

2. Run the Installer

The install script copies files from the source into a run directory, keeping your config and data separate from the source repo.

bash setup/install.sh

You'll be prompted to choose an installation directory:

  1. /opt/canectic
  2. ~/canectic
  3. Custom path

Then switch to the run directory for all remaining steps:

cd /opt/canectic    # or your chosen path

3. Set Up PostgreSQL

Create a database and user for Canectic. You can use the helper script or do it manually.

Option A: Helper script

bash setup/create_pg_db_user.sh

This prompts for a database name, username, and password. If it fails (common on systems where sudo -u postgres or createuser is restricted), use Option B instead.

Option B: Manual setup

Connect to PostgreSQL as the postgres superuser:

sudo -u postgres psql

Then run these commands (replace the values as desired):

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 a cluster whose initdb ran under a C or POSIX locale defaults to SQL_ASCII. SQL_ASCII performs no encoding validation whatsoever: invalid byte sequences are stored silently and returned unchanged, so any component writing non-UTF-8 corrupts data without raising an error. Message bodies carry CP437 art and accented names, so this matters in practice.

TEMPLATE template0 is what allows an encoding different from the cluster default. Keeping LC_COLLATE and LC_CTYPE as C means any encoding is permitted, sorting is byte order, and case folding stays ASCII-only, which is what Canectic already expects.

Check what you ended up with:

SELECT pg_encoding_to_char(encoding), datcollate, datctype
  FROM pg_database WHERE datname = 'canectic_bbs';

PostgreSQL 15+ changed the default permissions on the public schema. You must grant access explicitly. Connect to the new database and grant permissions:

\c canectic_bbs
GRANT ALL ON SCHEMA public TO canectic;
\q

Verify the connection works:

psql -U canectic -h localhost -d canectic_bbs

If prompted for a password, enter what you set above. If the connection fails with "peer authentication failed", ensure pg_hba.conf allows password auth for local connections (change peer to md5 or scram-sha-256 for the local IPv4/IPv6 lines, then sudo systemctl reload postgresql).

Remember the database name, username, and password -- you'll need them for .env.

4. Configure Environment

Edit .env (created from examples/env.example during install):

$EDITOR .env

Required settings:

dbuser=canectic          # PostgreSQL username (from step 3)
dbhost=localhost
dbname=canectic_bbs      # Database name (from step 3)
dbpass=YOUR_PASSWORD      # Password (from step 3)

Optional but recommended:

boardname=My BBS          # Displayed in nav bar, origin lines, mailer
SYSOP_USERNAME=YourName   # Sysop username for PM system notifications
mail_domain=mybbs.example.com  # Required for IMAP/SMTP and internet email

All other configuration is managed through the Admin UI at /admin/config after first login. For a full walkthrough of the mail subsystem (outbound SMTP relay, inbound gateway, mail client access, user verification), see MAIL.md.

5. Install Dependencies

npm install

This resolves the native addons. bcrypt, node-pty and @serialport/bindings-cpp build from source when no prebuilt binary matches your platform, which is why build-essential and python3 are required. better-sqlite3 v13 ships prebuilt binaries and does not compile.

On npm 12 and later, which ships with Node 26, dependency install scripts are blocked unless allowed. Canectic ships the allowlist, so this step needs no action; see the troubleshooting section if you see a block warning.

6. Run Database Migrations

node src/tools/dbmigrations.js

This creates all tables and columns. Safe to run multiple times: it only adds what's missing.

7. Start the BBS

With PM2 (recommended for production):

pm2 start ecosystem.config.cjs
pm2 save                                # what the boot unit will start
node src/tools/bootUnit.js --install    # start it at boot (asks for sudo)

Use bootUnit.js rather than pm2 startup. The unit pm2 startup writes hardcodes the Node version and stops booting once that version is removed; see Surviving Node Upgrades.

Single process (development/testing):

PROCESS_MODE=embedded node bin/gateway.js

Direct multi-process (without PM2):

node bin/gateway.js &
node bin/worker.js &
node bin/mail.js &
# Only if FTN mailer is needed:
MAILER_ENABLED=true node bin/mailer.js &

8. Create Your Sysop Account

The first user to register is automatically promoted to Sysop with full admin access.

The terminal starts with three menus, Main, Messages and Files (see "The Starter Menus" in MENUS.md); edit them under Menus > Menu Editor.

Web: Open http://localhost:8080/users/register and complete the registration wizard.

Terminal: Connect with a terminal client:

telnet localhost 2023

Choose "New User" and complete registration.

9. Verify

  • Web UI: http://localhost:8080 should show the landing page
  • Admin panel: http://localhost:8080/admin is accessible after logging in as Sysop
  • Health check: http://localhost:8080/health should return {"status":"ok","postgres":"ok","redis":"ok"}
  • Terminal: telnet localhost 2023 should show terminal negotiation and the login prompt
  • Everything else: once you are logged in as sysop, System Info on the admin dashboard checks Node, PostgreSQL, Redis, the processes and the programs Canectic uses, and says what is missing. See SYSTEM_INFO.md

Process Model

Canectic runs as four independent processes, all sharing PostgreSQL and Redis:

Process Script Purpose
Gateway bin/gateway.js Web UI, terminal connections, WebSocket pools
Worker bin/worker.js Message tossing (FTN/QWK/NNTP/Email), maintenance jobs
Mail bin/mail.js IMAP and SMTP servers for mail client access
Mailer bin/mailer.js FTN binkp mailer sessions (requires MAILER_ENABLED=true)

For development or simple setups, use PROCESS_MODE=embedded to run everything in a single process.

PM2 commands:

pm2 start ecosystem.config.cjs    # start all
pm2 restart gateway                # restart one process
pm2 logs worker                    # tail logs
pm2 monit                          # live monitoring dashboard

Surviving Node Upgrades

pm2 startup generates a systemd unit that hardcodes the Node version in both PATH and every Exec* line:

Environment=PATH=/home/you/.nvm/versions/node/v26.8.1/bin:...
ExecStart=/home/you/.nvm/versions/node/v26.8.1/lib/node_modules/pm2/bin/pm2 resurrect

Under nvm that pins the service to whichever Node was current the day the unit was generated. After nvm alias default 27 the BBS still boots on 26, and once 26 is uninstalled it stops booting at all.

A native Node install has a milder version of the same problem: the unit points at /usr/bin/pm2, which keeps working, but an OS upgrade can move the Node underneath it without warning.

Canectic ships a wrapper, setup/canectic-pm2.sh, that resolves Node at start time instead of freezing it into the unit. It follows nvm's default alias when nvm is present and falls back to whatever pm2 is on PATH when it is not, so the same unit works on both kinds of install. On resurrect it also notices processes that dump.pm2 recorded on a Node that has since been replaced, and restarts them on the current one and saves, which used to need a pm2 save by hand after every Node upgrade.

One command installs the wrapper and writes the unit that uses it, in place of pm2 startup and the hand edit this section used to describe. Run it as the user the BBS runs as, from the install directory:

node src/tools/bootUnit.js --install

It copies the wrapper to ~/.local/bin/canectic-pm2 (outside the install, because an update replaces setup/ and a boot in the middle of one would find no wrapper), writes /etc/systemd/system/pm2-<user>.service with sudo, keeping the PATH of any unit already there minus its Node version directories and saving the old one beside it as .before-canectic, and enables it. It restarts nothing: the new unit takes effect at the next boot, or now, at a quiet moment. If the unit was already running pm2:

pm2 save && sudo systemctl restart pm2-<user>

If you started pm2 yourself (with pm2 start, as on a fresh install), stop that daemon first, or the unit fails to start: its resurrect only talks to the daemon you started, and systemd refuses to adopt a process it did not start. The tool prints whichever applies.

pm2 save && pm2 kill && sudo systemctl start pm2-<user>

To see what it would write, or check a board without changing anything:

node src/tools/bootUnit.js --print      # the unit, to stdout
node src/tools/bootUnit.js              # what is wrong, if anything; exits 1 when something is

The check reports a unit pinned to a Node version, one that does not use the wrapper, a wrapper that is missing or older than the release's copy (run --install again after an update that changed it), processes in dump.pm2 on a Node that is no longer the default, and a dump.pm2 with nothing saved. The Update page shows the same warnings.

Upgrading Node then needs no unit edit and no pm2 save. Under nvm:

nvm install 27 && nvm alias default 27
npm install -g pm2                  # globals are per-version under nvm
sudo systemctl restart pm2-<user>

Natively, the package upgrade replaces Node in place:

sudo apt install --only-upgrade nodejs
sudo systemctl restart pm2-<user>

Upgrading the operating system underneath a running BBS is a separate job with its own risks, chiefly the PostgreSQL cluster. See OS_UPGRADE.md.

Without the wrapper (a unit from pm2 startup), a Node upgrade also needs a pm2 save, or the daemon comes up on the new Node while resurrect still spawns the four processes under the old interpreter recorded in the dump. ecosystem.config.cjs pins interpreter to process.execPath, so a plain pm2 start ecosystem.config.cjs followed by pm2 save re-pins them to the daemon's own Node, which is what the wrapper does for you. Verify with:

pm2 jlist | python3 -c "import json,sys; [print(p['name'], p['pm2_env']['node_version']) for p in json.load(sys.stdin)]"

Default Ports

Service Port Config Key Notes
Web / HTTP 8080 webport Web UI + WebSocket
Terminal 2023 terminalport Auto-detects TCP vs Telnet
IMAP 10143 imapport PM access from mail clients
SMTP Submission 10587 smtpport Send PMs from mail clients
Binkp (FTN) 24554 MAILER_BINKP_PORT FTN mailer (if enabled)
QWK hub FTP 8021 qwk_ftp_port Off unless qwk_ftp_enabled is on

Set any port to 0 to disable that listener. Port changes require a process restart.

The QWK hub FTP server is for QWK nodes that call your board over FTP (such as Synchronet's qnet-ftp.js). It is plain FTP, so passwords are not encrypted; over the internet the HTTP hub behind HTTPS is the better choice. If you turn it on behind a firewall or NAT, set qwk_ftp_pasv_ports to a range such as 50000-50100 and open that range as well as the control port, and set qwk_ftp_pasv_address to your public IPv4 address when the board is behind NAT.


Updating

From 0.9.6a onward

node src/tools/update.js --handoff    # stage the release, hand off to its updater
node src/tools/update.js --status     # what the last update did

Or press the button on /admin/update, which shows what is available, what applying it would do to your installation, and how many users are connected.

Either route closes the board for maintenance and warns callers and web users, waits for the board to drain, then stops the processes, replaces the files, installs dependencies, dumps the database, migrates it, runs the release's declared upgrade steps, starts everything again, checks every file it wrote and reopens the board. docs/sysop/MAINTENANCE.md covers what callers see. Your art, public/css/custom.css, door icons and anything you have edited under config/ are kept, and the update tells you what it left alone. Once an update completes it deletes the backups of older updates, keeping the last update_backup_keep (1 by default).

Everything it displaces is copied aside first. 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 dump are.

docs/sysop/UPDATING.md covers the flags, the phases and how to go back. docs/sysop/UPDATES.md covers the opt-in release check and taking releases over FTN.

From a source tree

The old path, needed once to get an installation from 0.9.5a or earlier onto 0.9.6a, and still supported afterwards.

cd /path/to/canectic-bbs-repo
git pull
bash setup/update.sh /opt/canectic

The update script:

  • Overwrites code files cleanly
  • Preserves your .env and data directories
  • Prompts before overwriting locally-modified config/data files
  • Installs/updates npm dependencies
  • Runs database migrations automatically

After the script completes, re-register the processes:

pm2 delete all && pm2 start ecosystem.config.cjs && pm2 save

pm2 restart is not enough. The four apps pin their interpreter when the config is evaluated, and pm2 resurrect replays the previously saved settings, so a restart can leave the board running on whichever Node was current when you last saved, with nothing to tell you.

One-time repairs

Migrations do not run one-time data repairs, because a repair that can only ever find something once should not scan every message table on every update. Where one is outstanding, the migration output says so and gives the command.

Currently there is one, the MSGID tuple split, for message bases written before msg_id and msg_orig_addr were separate columns. If migrations tell you it has not run:

node src/tools/maintenance.js --fix-msgids --dry-run   # report only
node src/tools/maintenance.js --fix-msgids             # repair

It needs the worker running, takes a while on a large message base, and only ever needs doing once. Migrations stop mentioning it afterwards.

A fresh install has nothing to repair and is marked done automatically, so you will only see this on a system carrying older message bases.


Directory Structure

After installation, your run directory contains:

/opt/canectic/
├── .env                    # Your configuration (not overwritten on update)
├── .canectic-update/       # Update staging, cached releases and update backups
├── ecosystem.config.cjs    # PM2 process configuration
├── bin/                    # Process entry points
├── src/                    # Application source code
├── db/                     # Schema definitions
├── public/                 # Static web assets
├── config/                 # Terminal themes, default menus
│   ├── default/            # Default menu configurations
│   └── themes/             # Terminal color themes
├── txtfiles/               # ANSI/ASCII art and text files
│   ├── ans/                # ANSI art files
│   └── asc/                # ASCII text files
├── ftn/                    # FTN network directories
│   ├── in/                 # Inbound packets
│   ├── out/                # Outbound packets
│   ├── tossed/             # Processed packets
│   ├── bad/                # Files that could not be tossed (Bad Files page)
│   └── tmp/                # Temp working directory
├── qwk/                    # QWK network packet staging
├── qnet/                   # QWK link packet directories: <ID>.hub/ and <ID>.node/
├── files/                  # File area storage
│   └── staging/            # Upload staging directory
├── logs/                   # Log files
│   ├── production/         # Process and PM2 logs
│   │   └── archive/        # Rotated logs, one directory per day
│   └── update/             # Record of every update run
├── xtrn/                   # Door game programs
├── setup/                  # Setup scripts
├── examples/               # Example configuration files
├── docs/                   # Documentation
│   ├── sysop/              # This guide and other sysop docs
│   └── reference/          # Architecture reference (developers)
└── tests/                  # Test suite

Log rotation

Every night at 23:59 each log in logs/production/ is compressed into logs/production/archive/YYYY-MM-DD/ and started afresh, and archives older than log_retention_days (30 by default, 0 keeps them all) are deleted. log_rotation_enabled turns it off, from the next gateway restart. To rotate now, or see what rotation would do, without the worker:

node src/tools/rotateLogs.js --dry-run
node src/tools/rotateLogs.js

Troubleshooting

"PostgreSQL is not reachable"

  • Check that PostgreSQL is running: sudo systemctl status postgresql
  • Verify credentials in .env match what you created in step 3
  • Test manually: psql -U canectic -h localhost -d canectic_bbs

"Redis is not reachable"

  • Check that Redis is running: sudo systemctl status redis-server
  • Verify redis_url in .env (default: redis://localhost:6379)
  • Test manually: redis-cli ping

Web UI shows "Internal Server Error"

  • Check the gateway logs: pm2 logs gateway
  • Ensure database migrations have run: node src/tools/dbmigrations.js

npm reports "install scripts blocked" for a native module

npm 12, which ships with Node 26, no longer runs dependency install and postinstall scripts by default. That is a supply chain measure: a package can no longer execute code on your machine simply by being installed. Packages must be listed in the allowScripts field of package.json.

Canectic ships that allowlist, so a normal install needs no action. Four dependencies are approved because their install script is what resolves the native binary, and nothing works without it:

Package Why it must run What breaks without it
bcrypt node-gyp-build password hashing, so nobody can log in
node-pty prebuild or node-gyp rebuild door games
@serialport/bindings-cpp node-gyp-build DOS doors over socat serial pairs
better-sqlite3 node-gyp rebuild Synchronet JS door data, on platforms with no prebuilt binary

better-sqlite3 is a special case worth understanding. It ships prebuilt binaries for Linux, macOS and Windows on x64 and arm64, including a musl variant, and on those platforms it never compiles: it loads prebuilds/<platform>-<arch>.node directly. It even sets gypfile: false in its manifest to say so. npm still flags it, because it keys off the binding.gyp file shipped in the package rather than that field. Blocking it is harmless on a mainstream platform, but it is approved anyway so that a system with no matching prebuild falls back to compiling rather than failing at first door launch with a missing-bindings error.

Three more are deliberately denied, because each is an optional accelerator with a working fallback: msgpackr-extract (an optional dependency of msgpackr, which uses a JavaScript path without it), cpu-features (an optional dependency of ssh2, whose require is wrapped in a try), and ssh2 itself, whose install script builds an optional crypto binding and exits successfully when that fails. Denying them costs a little SFTP and queue-serialisation speed and nothing else.

The four approvals are pinned to versions. After upgrading any of them you will see the block warning again, which is intended: re-approve deliberately with

npm install-scripts approve bcrypt node-pty @serialport/bindings-cpp better-sqlite3
npm install-scripts ls        # review anything still unreviewed

and commit the updated package.json. If you see the warning for a package not listed above, review it before approving rather than approving to clear the message.

Existing database is SQL_ASCII instead of UTF8

Installs created before the encoding was set explicitly inherited whatever template1 used, which on a C-locale cluster is SQL_ASCII. Check with:

SELECT pg_encoding_to_char(encoding), datcollate, datctype
  FROM pg_database WHERE datname = current_database();

Encoding cannot be altered in place, so converting means dumping and reloading into a new database. Because the collation stays C, sort order and case folding are byte-identical afterwards; the only change is that PostgreSQL starts validating bytes on write.

There is a script for this:

pm2 stop all
bash setup/convert_db_encoding.sh --source canectic_bbs
pm2 start ecosystem.config.cjs

The converted database takes over the original name and the old one is renamed aside to canectic_bbs_sqlascii_<timestamp>, so .env needs no change.

The order matters: it dumps, restores into a staging database, and compares row counts table by table, and only renames anything once that has passed. A failure at any earlier point leaves the original exactly where it was. Before starting it also scans every text column for bytes that are not valid UTF-8 and refuses if it finds any, since those would fail the reload.

Stopping the processes is required rather than advisory, and the script enforces it: PostgreSQL cannot rename a database while anything is connected. It refuses if it finds a connection, then sets CONNECTION LIMIT 0 on the source for the duration so nothing can reconnect part way through. An idle connection pool reports zero connections and will happily reconnect, which would put writes into the backup instead of the live database.

To roll back, stop everything and swap the two names again; the script prints the exact commands.

If you would rather keep the original in place and have the copy under a new name, pass --target. Nothing is renamed in that mode, and you repoint dbname in .env yourself:

bash setup/convert_db_encoding.sh --source canectic_bbs --target canectic_utf8

To check whether a database needs converting without changing anything:

bash setup/convert_db_encoding.sh --source canectic_bbs --preflight-only

Stop the processes first. A dump taken while the system is writing is internally consistent but misses anything committed after it starts.

The equivalent by hand, if you would rather do it yourself:

pg_dump -Fc canectic_bbs > canectic_bbs.dump
createdb -T template0 -E UTF8 --lc-collate=C --lc-ctype=C -O canectic canectic_utf8
pg_restore -d canectic_utf8 canectic_bbs.dump

pg_restore validates every byte on the way in, so an invalid sequence fails the restore loudly rather than corrupting the new database. If the restore succeeds, compare a few row counts, point dbname in .env at the new database, and restart. Keep the original database until you are satisfied.

Web login returns to the login page with no error

Terminal login works for the same account, but the web login form just redirects back to itself. Authentication is succeeding; the browser is discarding the session cookie.

  • Check sitetld (admin > config > network). It sets the cookie Domain, and the FQDN you browse must be at or under it. example.com covers bbs.example.com, but not example.org, and not a bare IP address.
  • Leave sitetld empty unless you need the session shared across subdomains. Empty sends a host-only cookie that always matches whatever host the request arrived on.
  • Confirm in browser devtools: if no sessionid cookie is stored after the login POST, it is the domain mismatch. If the cookie is present and you are still bounced, look at Redis instead (redis-cli ping), since a failed session write shows an explicit "Login failed" error rather than a silent redirect.

Terminal connection hangs or drops

  • Verify terminalport is not 0 in your config
  • Check firewall rules: sudo ufw status
  • Try raw TCP: nc localhost 2023

Native addon build failures (npm install)

  • Ensure build-essential and python3 are installed
  • For node-pty: may need sudo apt install libutil-dev on some systems
  • Try clearing and rebuilding: rm -rf node_modules && npm install

Health check returns 503

  • One or both databases are unreachable
  • Check the response body for which service is down
  • curl -s http://localhost:8080/health | python3 -m json.tool