xthulu
xthulu copied to clipboard
Python asyncio community server (HTTPS, SCP, SFTP, SSH) with a modern terminal interface
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
Terminal server checklist
Terminal server
- [x] SSH server (AsyncSSH)
- [x] Password authentication
- [x] Guest (no-auth) users
- [ ] Key authentication
- [x] PROXY v1 support
- [ ] SCP subsystem
- [ ] SFTP subsystem
- [x] Composite userland script stack
- [x] Goto
- [x] Gosub
- [x] Exception handling
- [x] Terminal library (rich)
- [x] Adapt for SSH session usage
- [ ] UI components (textual)
- [x] Adapt for SSH session usage
- [ ] File browser
- [ ] Message interface
- [x] List messages
- [x] Post messages
- [x] Reply to messages
- [x] Tag system
- [x] Filter by tag(s)
- [ ] Search messages
- [ ] Private messages
- [ ] Door games
- [x] Subprocess redirect for terminal apps
- [ ] Dropfile generators
- [ ]
DOOR.SYS
- [ ]
DORINFOx.DEF
- [ ]
Miscellaneous checklist
Miscellaneous
- [x] Container proxy (Traefik)
- [x] HTTP server (uvicorn)
- [x] Basic authentication
- [x] Web framework (FastAPI)
- [x] Composite userland
- [x] Static files
- [ ] IPC
- [x] Session events queue
- [x] 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.)
- [x] Locks (IPC semaphore)
- [ ] Global IPC (CLI, web, etc.) via Redis PubSub
- [ ] Data layer
- [x] PostgreSQL for data
- [x] Asynchronous ORM (GINO)
- [x] User model
- [x] 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 theetc/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.