xthulu

xthulu ("ch-THOO-loo") Python asyncio community server

While xthulu is intended to be a community server with multiple avenues of interaction (e.g. terminal, browser, REST API), its primary focus is to provide a modern SSH terminal interface which pays homage to the bulletin boards of the 1990s. Rather than leaning entirely into DOS-era nostalgia, modern character sets (UTF-8) and terminal capabilities are taken advantage of.

• 📔 Contributor guide
• 📽️ Demo video (animated GIF)

Progress

📊 Alpha release project board

Terminal server checklist

Terminal server

• SSH server (AsyncSSH)
  • Password authentication
  • Guest (no-auth) users
  • Key authentication
• PROXY v1 support
• SCP subsystem
• SFTP subsystem
• Composite userland script stack
  • Goto
  • Gosub
  • Exception handling
• Terminal library (rich)
  • Adapt for SSH session usage
• UI components (textual)
  • Adapt for SSH session usage
  • File browser
  • Message interface
    • List messages
    • Post messages
    • Reply to messages
    • Tag system
    • Filter by tag(s)
    • Search messages
    • Private messages
• Door games
  • Subprocess redirect for terminal apps
  • Dropfile generators
    • DOOR.SYS
    • DORINFOx.DEF

Miscellaneous checklist

Miscellaneous

• Container proxy (Traefik)
• HTTP server (uvicorn)
  • Basic authentication
  • Web framework (FastAPI)
    • Composite userland
  • Static files
• IPC
  • Session events queue
  • Methods for manipulating queue (querying specific events, etc.)
  • Can target other sessions and send them events (gosub/goto, chat requests, IM, etc.)
  • Server events queue (IPC coordination, etc.)
  • Locks (IPC semaphore)
  • Global IPC (CLI, web, etc.) via Redis PubSub
• Data layer
  • PostgreSQL for data
  • Asynchronous ORM (GINO)
  • User model
  • Message bases
  • Simple pickle table for miscellaneous data storage?

Setup

# in the project root
etc/setup.sh

Manual steps

---

If you want to perform the steps in the setup script manually for some reason, here they are:

Create a configuration file and generate host keys

# in the data/ directory
cp config.example.toml config.toml
ssh-keygen -f ssh_host_key -t rsa -b 4096 -N ""

Build the docker images

# in the docker/ directory
docker compose build base-image
docker compose pull --ignore-buildable

Create and seed the database

Note the names of the scripts. The etc/cli.sh script is the command line interface for server tasks, while the etc/userland.sh script is for userland.

# in the project root
etc/cli.sh db create --seed
etc/user.sh db create --seed

Build the static web assets

# in the project root
etc/build-web.sh

---

Start the services

# in the docker/ directory
docker compose up -d

Connect

Connect to the terminal server

There is a guest account which demonstrates the ability for some accounts to bypass authentication.

ssh guest@localhost

There is also a user account with a password for testing password authentication.

ssh user@localhost  # password is also "user"

Connect to the web server

For the time being, the web server only demonstrates simple interoperability between the REST API and static pages. It is available at https://localhost. There is a demo application that can be used for chatting with other users connected via both the web and the SSH server.

⚠️ Traefik will be using an untrusted certificate, and you will likely be presented with a warning.

The same credentials may be used here; for the guest account, any password (or a blank password) will work.