# 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 ```bash # 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: ```bash 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. ```bash 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: ```bash 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 ```bash 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) ```bash 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. ```bash # 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 ```bash 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: ```bash 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 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 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](https://gitlab.tranqsoft.com/drog007/canectic/-/releases) and extract: ```bash unzip canectic-0.9.12a.zip cd canectic-0.9.12a ``` **From git (specific release):** ```bash git clone --branch v0.9.12a --depth 1 https://gitlab.tranqsoft.com/drog007/canectic.git cd canectic ``` **From git (latest development):** ```bash 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 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: ```bash 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 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: ```bash sudo -u postgres psql ``` Then run these commands (replace the values as desired): ```sql 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: ```sql 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: ```sql \c canectic_bbs GRANT ALL ON SCHEMA public TO canectic; \q ``` Verify the connection works: ```bash 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): ```bash $EDITOR .env ``` **Required settings:** ```ini 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:** ```ini 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](MAIL.md). ### 5. Install Dependencies ```bash 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 ```bash 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):** ```bash 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](#surviving-node-upgrades). **Single process (development/testing):** ```bash PROCESS_MODE=embedded node bin/gateway.js ``` **Direct multi-process (without PM2):** ```bash 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](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: ```bash 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](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: ```bash 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: ```ini 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: ```bash 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-.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: ```bash pm2 save && sudo systemctl restart pm2- ``` 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. ```bash pm2 save && pm2 kill && sudo systemctl start pm2- ``` To see what it would write, or check a board without changing anything: ```bash 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: ```bash nvm install 27 && nvm alias default 27 npm install -g pm2 # globals are per-version under nvm sudo systemctl restart pm2- ``` Natively, the package upgrade replaces Node in place: ```bash sudo apt install --only-upgrade nodejs sudo systemctl restart pm2- ``` Upgrading the operating system underneath a running BBS is a separate job with its own risks, chiefly the PostgreSQL cluster. See [OS_UPGRADE.md](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: ```bash 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 ```bash 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. ```bash 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: ```bash 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: ```bash 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: .hub/ and .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: ```bash 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/-.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 ```bash 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: ```sql 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: ```bash 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_`, 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 bash setup/convert_db_encoding.sh --source canectic_bbs --target canectic_utf8 ``` To check whether a database needs converting without changing anything: ```bash 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: ```bash 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`