https://github.com/robbiew/retrograde
Retrograde is an old-school Bulletin Board System (BBS) built for modern use. It seeks to replicate many features of classic BBS software -- while adding some new ones.
https://github.com/robbiew/retrograde
ansi-art bbs console-application go textmode
Last synced: 5 months ago
JSON representation
Retrograde is an old-school Bulletin Board System (BBS) built for modern use. It seeks to replicate many features of classic BBS software -- while adding some new ones.
- Host: GitHub
- URL: https://github.com/robbiew/retrograde
- Owner: robbiew
- License: mit
- Created: 2025-10-07T02:40:49.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-11-21T13:22:58.000Z (7 months ago)
- Last Synced: 2025-11-21T15:16:19.114Z (7 months ago)
- Topics: ansi-art, bbs, console-application, go, textmode
- Language: Go
- Homepage:
- Size: 510 MB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Retrograde BBS
| | |
| :--------------------------------------------------------: | :---------------------------------------------: |
|  |  |
|  |  |
Retrograde is a retro-style Bulletin Board System (BBS) implemented in Go. The project has achieved **moderate functional completeness** for some core BBS operations and is test-ready. Active development continues on advanced features like file areas and transfer protocols. Don't use in production yet!
## AI Trigger warning
I use LLMs strategically to guide work that would otherwise take months of trial-and-error in my limited free time. Most LLM-related contexts and notes are documented in the `memory-bank/` and in `.github/` folders for transparency.
## Core Objectives
- Open and transparent development: contributors welcome!
- Targeting Linux (including Raspberry Pi). Some functions might not yet work on Windows or Mac yet
- Classic BBS experience: Maintain the spirit and look & feel of software like Telegard, Renegade, Iniquity, ViSiON-X
## Planned Feature Status
| Feature | Progress | Notes |
| ------------------------------- | -------- | ------------------------------------------------------------------------------- |
| Installation | 100% | Install and build scripts, including external deps |
| Telnet Server | 100% | Completed with full session |
| Binkd Server | 100% | External dependency, runs as a child process |
| Security System | 100% | White/Blocklist support, GeoIP filtering, Rate Limiting |
| SQLite Database | 100% | Seeds sensible defaults on initialization |
| TUI Configuration Editor | 100% | View and edit configuration in Terminal UI application |
| Automatic First-Time Setup | 100% | Creates database with sensible defaults automatically |
| ANSI Art Support | 100% | Print up to 80 col ansi art, automatic SAUCE record stripping |
| Session Management | 100% | Idle timeout, disconnection, time tracking |
| Node Management | 100% | Max nodes, per-user limits, node directories, logging |
| Auth /Login UI | 100% | Create New User, Login with direct auth flow |
| Timed Event System | 100% | Do things on a timed/recurring schedule (example poll & maint scripts included) |
| Menu Construction System | 100% | Renegade-style approach for constructing menus and prompts |
| Menu Execution | 100% | Execute Menu Command Logic (stacking, first run, special keys) |
| Message Base Configuration & UI | 100% | Conference > Area creation and management hierarchy |
| JAM message files | 100% | Format implementation, read/write, lastread tracking |
| Message Base (FTN) Support | 100% | JAM format, Husky/hpt and binkd config generation |
| Message Base New Scan | 100% | Scan subscribed areas from Last Read pointers |
| Message Base Subscriptions | 100% | Subscribe/Unsubscribe to areas for New Scan with MZ command |
| JAM Utility (jamutil) | 100% | Complete replacement for hptutil - [Details](docs/jamutil-go-replacement.md) |
| FTN mailer | 100% | Binkd support built in, binkd.conf auto generation |
| Netmail Support | 100% | Type defined, basic "Private mail" menu |
| Private Email Support | 100% | Support user-to-user local private mail |
| Message Editor (basic) | 100% | Classic DOS editors like IceEdit, DCTEdit, and new StormEdit (Linux) |
| Message Reader (basic) | 100% | UI integration with basic template and MCI code support |
| Linux Doors | 100% | Native PTY execution, environment variables, full I/O |
| DOS Door Support | 100% | DOSEMU2 integration, DOOR.SYS/door32.sys/DORINFO#.DEF dropfiles |
| Pipe Colors | 100% | Support for Renegade-style pipe colors |
| Color Themes | 100% | Support for color themes |
| Python Scripting | 100% | Python3 scripting with pipe color support, BBS API functions |
| User Settings Menu | 100% | Allow users to change Personal Settings |
| MCI Codes | 25% | Template system with visual placeholder support, needs expansion |
| Menu Commands | 35% | [List](docs/menu-commands.md) - Core navigation & door commands done |
| File Area Management | 80% | Database schema and TUI configuration complete |
| File Area UI | 80% | List and search files |
| Echo File Area UI | 5% | Basic structure planned |
| TIC File Area Processing | 0% | Database schema supports TIC processing |
| Mass Import Files | 100% | Database schema supports batch imports using 'helper' binary |
| Upload/Download Functions | 100% | Complete - SEXYZ + lrzsz protocols, TUI configuration, menu integration |
| Archivers | 100% | zip, arj, lzh, etc. |
| Achievements | 0% | Implement achievement tracking and rewards |
| SSH Server | 0% | Not started |
| TelnetS Server | 0% | Not started |
| 132x37 art support | 0% | Not started |
| Ansi Art Gallery | 0% | Not started |
| One-Liners | 0% | Not started |
| Local Last 10 Callers | 0% | Not started |
| Network Last Callers | 0% | Not started |
| Users Online Now | 0% | Not started |
| Node Messaging | 0% | Not started |
| User List | 0% | Not started |
| System Information | 0% | Not started |
| MRC Chat | 0% | Not started |
| RLOGIN Server | 0% | Not started |
| Game Server Mode | 0% | Not started |
| Connect to Game Servers | 0% | Not started |
| Built-in Web Server | 0% | Not started |
| Web-Based Messaging | 0% | Not started |
| Built-in File Access/Download | 0% | Not started |
| Discord Notifications | 0% | Not started |
| SMTP Integration | 0% | Not started |
| Forgot/Reset PW Function | 0% | Not started |
## External Dependencies
Retrograde includes an automated system for managing external Fidonet utilities required for message processing:
### Bundled Utilities
- **Husky HPT** - FTN message processor for importing/exporting echomail and netmail
- **Binkd** - Mailer daemon for FTN message exchange with other nodes
- **StormEdit** - Modern cross-platform message editor with UTF-8 support
For detailed information, see `docs/building-external-dependencies.md`.
## Quick Start
### System Dependencies
For full functionality, you may want to install additional system packages. See [docs/package-requirements.md](docs/package-requirements.md) for detailed installation commands for your distribution.
**Quick install for Ubuntu/Debian:**
```bash
sudo apt-get install golang-go build-essential git curl wget tar zip unzip python3
```
*Note: DOSemu2 requires adding a PPA first - see the full documentation for details.*
## Installation
### Build from Source
The easiest way to install Retrograde is using the installation script:
```bash
chmod +x install.sh
./install.sh
```
The installer will:
1. Prompt for installation directory (default: `~/retrograde`)
2. **Download external dependencies** (Husky HPT, Binkd, StormEdit)
3. Build a fresh binary from source
4. Copy all content files (themes, doors, docs)
5. Set up directory structure
After installation:
```bash
cd ~/retrograde # or your chosen directory
./retrograde config # Configure BBS settings
./retrograde # Start the server
```
**Message Base Maintenance:**
```bash
# JAM message base utilities (replaces buggy `hptutil`):
bin/jamutil sort link pack # Sort, link, and pack message areas
bin/jamutil fix # Check message base integrity
bin/jamutil purge # Remove old messages per retention settings
```
## Command Line Options
- `./retrograde` - Run the server (creates database with defaults if needed)
- `./retrograde config` (or -config, --config, /config) - Launch configuration editor
## Documentation
Comprehensive documentation is available in the `docs/` directory:
### User Guides
- **[Helper Tool Guide](docs/helper-tool.md)** - File management and bulk operations 🤖
- **[File Storage Architecture](docs/file-storage.md)** - How the content-addressed storage system works 📁
### System Administration
- **[First Time Setup](docs/first-time-use.md)** - Getting your BBS running
- **[Door Games](docs/doors.md)** - Setting up classic BBS games
- **[Python Scripts](docs/python-scripts.md)** - Custom scripting and automation
## Security File Management
The server uses IP allowlist and blocklist files for access control. These files don't exist, create them if you want to se them:
**Blocklist** (`security/blocklist.txt`):
```text
# Format: IP_ADDRESS REASON
1.2.3.4 Known spam source
192.168.100.0/24 Blocked subnet range
```
**Allowlist** (`security/allowlist.txt`):
```text
# Format: IP_ADDRESS REASON
127.0.0.1 Localhost
192.168.1.100 Admin home IP
203.0.113.0/24 Trusted ISP range
```
**Features:**
- Comments start with `#`
- Supports individual IPs and CIDR ranges
- Allowlist takes priority over blocklist
- Files are loaded at server startup
- Auto-populated by rate limiting system
## Data Storage
All BBS data is stored in SQLite database, e.g. default (`data/retrograde.db`):
- **User accounts**: Authentication, profiles, and preferences
- **Configuration**: Server settings and BBS configuration
- **Sessions**: Active user sessions and node management
- **Security**: Audit logs and threat intelligence data
**Security Logs** (`logs/` directory):
- Security events logged to `logs/security.log`
- Connection attempts, blocks, and system events
- Daily logs in `logs/YYYY-MM-DD.log` format
## Project Structure
This project follows the [Standard Go Project Layout](https://github.com/golang-standards/project-layout):
```text
retrograde/
├── cmd/
│ └── server/ # Main BBS server binary
├── content/ # Content assets for the BBS (themes, doors, scripts)
│ ├── DOS/ # DOSEMU2 configuration templates
│ ├── doors/ # Door game files (LORD, IceEdit, StormEdit, etc.)
│ ├── scripts/ # Python scripts and utilities
│ └── theme/ # ANSI art themes and templates
├── docs/ # Documentation, design notes, and research
├── internal/ # Private application packages
│ ├── auth/ # User authentication, registration, and session management
│ ├── binkd/ # Binkd mailer integration and configuration
│ ├── color/ # Color theme system and pipe color support
│ ├── config/ # Configuration management and database integration
│ ├── database/ # SQLite database layer and schema management
│ ├── door/ # Door system (dropfiles, execution, DOSEMU2)
│ ├── editor/ # Message editor system (internal/external)
│ ├── event/ # Timed event system and scheduler
│ ├── filesystem/ # Filesystem operations and utilities
│ ├── hpt/ # HPT integration for FTN message processing
│ ├── husky/ # Husky FTN config generation
│ ├── jam/ # JAM message base format implementation
│ ├── logging/ # Logging utilities and node management
│ ├── mci/ # MCI code processing and template system
│ ├── menu/ # Menu construction system, rendering, and navigation
│ ├── networking/ # Network configuration and FTN address management
│ ├── python/ # Python scripting bridge and API
│ ├── security/ # Security system (rate limiting, geo-blocking, threat intel)
│ ├── sys/ # System utilities and platform-specific code
│ ├── telnet/ # Telnet I/O and protocol handling
│ ├── tui/ # Configuration TUI (Terminal User Interface)
│ └── ui/ # UI utilities (ANSI art, terminal handling, colors)
├── memory-bank/ # Development documentation (AI notes, design docs, etc.)
├── release/ # Build artifacts and release binaries
├── scripts/ # Build and utility scripts
└── third_party/ # External dependencies and build configurations
```
## Requirements
- Go 1.24+
- Modern terminal/telnet client with ANSI support (like Syncterm, Netrunner, Icy_Term or MagiTerm)
## Dependencies
### Go Dependencies
- `github.com/charmbracelet/bubbletea` - Terminal UI framework
- `github.com/charmbracelet/lipgloss` - Terminal styling
- `modernc.org/sqlite` - SQLite database
- `github.com/mattn/go-isatty` - Terminal detection
- `golang.org/x/text` - Text processing utilities
- `github.com/google/uuid` - UUID generation
---
Part of the *Retrograde BBS* project.