getting-started.md

Getting Started

OxideBBS is a BBS server for sysops who want ANSI/CP437 callers, telnet and browser-terminal access, DOS doors, file areas, local sysop tools, and FTN or OxideNet networking.

Choose the install path that matches how you want to operate the board:

Path	Best for	Complexity
Docker	Fastest cross-platform setup, including DOSEMU2 for doors.	Easiest
Release binaries	Running directly on Linux, macOS, or Windows without compiling Rust.	Moderate
Build from source	Development, custom patches, or unsupported targets.	Most involved

Most new sysops should start with Docker. Use release binaries when you want a normal service install on a host you manage. Build from source only when you are working on OxideBBS itself or need to patch it.

Option 1: Docker

Docker keeps DecentDB, door runtime files, and DOSEMU2 on a Linux filesystem even when the host is Windows or macOS.

docker compose pull
OXIDEBBS_SYSOP_PASSWORD='choose-a-real-password' docker compose up -d

Connect with SyncTERM or another telnet client:

localhost:2323

Run sysop commands through Compose:

docker compose run --rm oxidebbs status
docker compose run --rm oxidebbs nodes list
docker compose run --rm oxidebbs doors check oxide-check

See Docker Deployment for volume layout, reset steps, and door notes.

Option 2: Release binaries

Download the archive for your platform from the GitHub release page:

oxidebbs-<version>-linux-x86_64-gnu.tar.gz
oxidebbs-<version>-macos-x86_64.tar.gz
oxidebbs-<version>-windows-x86_64-msvc.zip

Each archive has a matching .sha256 file. Extract the archive, then run the binary from the extracted directory:

./oxidebbs-server --version
./oxidebbs-server setup
./oxidebbs-server --config config/oxidebbs.toml check
./oxidebbs-server --config config/oxidebbs.toml serve

The release archive includes the server binary, default assets, example config, and the Oxide-owned oxide-check test door fixture. Linux hosts that launch DOS doors still need DOSEMU2 installed on the host unless you use Docker.

See Release Binaries for install and service notes.

Option 3: Build from source

Use this path when you are developing OxideBBS or need local patches.

Prerequisites:

sudo apt-get install -y clang libclang-dev

Build and run from the repository:

cargo build --release --locked -p oxidebbs-server --bin oxidebbs-server
./target/release/oxidebbs-server setup
./target/release/oxidebbs-server --config config/oxidebbs.toml check
./target/release/oxidebbs-server --config config/oxidebbs.toml serve

If you are changing OxideBBS source code, run the contributor quality gate before opening a pull request:

./scripts/dev-check.sh

First board setup

The setup wizard creates a board config, DecentDB database, initial sysop account, directories, default ANSI/screen assets, and the starter message area:

oxidebbs-server setup

For unattended setup:

oxidebbs-server setup \
  --board-name "My BBS" \
  --sysop-alias sysop \
  --sysop-password "change-this" \
  --nodes 4

The generated config is usually:

config/oxidebbs.toml

Validate it before first boot:

oxidebbs-server --config config/oxidebbs.toml check
oxidebbs-server --config config/oxidebbs.toml config check

Start the BBS

oxidebbs-server --config config/oxidebbs.toml serve

The server accepts caller sessions, writes session/audit rows, and starts the local control socket at:

runtime/oxidebbs-control.sock

Use local sysop commands while the server is running:

oxidebbs-server --config config/oxidebbs.toml status
oxidebbs-server --config config/oxidebbs.toml nodes list
oxidebbs-server --config config/oxidebbs.toml nodes watch

Enable browser terminal and LAN monitoring

When [admin_web].enabled = true, OxideBBS can serve /terminal, /health, and /status from the same HTTP listener. Direct LAN HTTP is allowed; WAN or public HTTPS should be handled by a reverse proxy.

See Remote Monitoring for safe bind examples.

Doors

OxideBBS includes an Oxide-owned oxide-check test door fixture for validating the door path. Validate it without launching DOSEMU2:

oxidebbs-server --config config/oxidebbs.toml doors check oxide-check
oxidebbs-server --config config/oxidebbs.toml doors test oxide-check --user sysop --dry-run

Live DOS doors use this byte path:

caller client
  <-> OxideBBS caller transport
  <-> OxideBBS PTY byte bridge
  <-> DOSEMU2 COM1 pts backend
  <-> DOS door program

Linux hosts running live DOS doors need DOSEMU2. Fedora sysops should use the DOSEMU2 on Fedora guide.

File areas

Enable [file_transfers], create a file area, then import files:

oxidebbs-server --config config/oxidebbs.toml files areas add main \
  --name "Main Files" \
  --root files/main \
  --read-level 0 \
  --download-level 0 \
  --upload-level 20

oxidebbs-server --config config/oxidebbs.toml files import main ./uploads/demo.zip \
  --description "Demo archive"

Callers can download with ZMODEM or XMODEM from the configured files menu. Uploads are stored pending sysop review.

Backups

oxidebbs-server --config config/oxidebbs.toml db backup backups/oxidebbs.ddb
oxidebbs-server --config config/oxidebbs.toml db export --format json > backups/oxidebbs.json
oxidebbs-server --config config/oxidebbs.toml db compact --output backups/oxidebbs-compacted.ddb

db import --format json is a full restore into a schema-only target. Stop the server before manually replacing the active database file.

Where to go next

• Setup Wizard explains generated config and starter assets.
• Docker Deployment covers Docker volumes and door runtime notes.
• Release Binaries covers packaged installs.
• Menus explains caller menus and help screens.
• Doors covers local and remote door setup.
• File Transfers covers ZMODEM and XMODEM behavior.
• FTN Architecture covers echomail and netmail.
• OxideNet covers first-party OxideNet workflows.