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.
Install with nvm (recommended)
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:
/opt/canectic~/canectic- 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:8080should show the landing page - Admin panel:
http://localhost:8080/adminis accessible after logging in as Sysop - Health check:
http://localhost:8080/healthshould return{"status":"ok","postgres":"ok","redis":"ok"} - Terminal:
telnet localhost 2023should 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 |
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
.envand 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
.envmatch 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_urlin.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 cookieDomain, and the FQDN you browse must be at or under it.example.comcoversbbs.example.com, but notexample.org, and not a bare IP address. - Leave
sitetldempty 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
sessionidcookie 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
terminalportis 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-essentialandpython3are installed - For node-pty: may need
sudo apt install libutil-devon 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