Project Chimera is an immersive, game-like web terminal operating within a fully functional Unix environment. My goal was to create a unique narrative that unfolds directly through shell commands. As an Investigator, you'll navigate a Filesystem, encountering critical anomalies via a real Bash shell on an isolated Alpine Linux instance.
The Game is not very good. But the time I spent building it was.
- Authentic Terminal:
xterm.jsprovides full-featured terminal emulation. - Isolated Sessions: Each connection spawns a new, disposable Docker container for user isolation.
- Interactive Narrative: In-game actions (e.g., file interactions) trigger frontend animations and backend events.
- Customization: Personalized MOTD, prompt, and custom
less/viwrappers for game integration. - Secure Environment: Strict Docker container limits (
--read-only,--tmpfs /home,--network=none), hardened permissions (700,740,640), and isolated user accounts. - Robust Logging (Optional): Designed with an option for logging user inputs into an SQLite database (currently disabled).
- Game Complete Screen: An animated end screen signals successful completion.
-
Frontend: HTML, CSS, JavaScript,
xterm.js. -
Backend: Node.js (v20 LTS), Express.js,
express-ws,node-pty(PTY management). -
Containerization: Docker Engine (Alpine Linux base for terminal containers).
-
Web Server/Proxy: Nginx (SSL/TLS via Certbot).
-
Process Management: PM2.
-
Operating System: Ubuntu 24.04 LTS VM.
The project uses a client-server architecture with Docker providing isolation:
- Client (Browser): Loads static frontend from Nginx. Establishes a
wss://WebSocket connection to Nginx. - Nginx (Reverse Proxy): Serves frontend static files. Proxies WebSocket connections (
/path) to the Node.js backend. Handles HTTPS. - Node.js Backend (
server.js): Runs on the host VM (managed by PM2). Spawns and manages uniqueterminal-containerDocker instances for each WebSocket session. Orchestrates game events by monitoring container output and executingdocker execcommands for in-game actions. - Terminal Container: An isolated Alpine Linux Docker image with a Bash shell. Its
entrypoint.shsets up the user environment and custom command wrappers.
This guide assumes a fresh Ubuntu 24.04 LTS VM with SSH access and your project cloned to /home/youruser/project-chimera.
sudoaccess.- A non-root user account
- A domain name pointing to your VM's public IPv4.
-
Run VM Preparation Script: Installs Docker, Node.js, PM2, Nginx, Certbot.
cd /home/$USER/project-chimera chmod +x deploy_prep.sh ./deploy_prep.sh # Follow prompts (domain name). # Crucial: Log out/in, then run ./deploy_prep.sh again to complete.
-
Perform Full Project Deployment: Copies frontend, builds Docker images, starts backend.
chmod +x deploy.sh # Set your domain name as an environment variable before running export DOMAIN_NAME="projectchimera.xyz" sudo ./deploy.sh
- Access
https://yourdomain.com/in your browser. - Check
pm2 status,pm2 logs web-terminal-backend,sudo systemctl status nginxon your VM for errors. - Verify firewall rules (
sudo ufw status verbose).
Navigate to https://projectchimera.xyz/ in your web browser. Interact with the terminal using standard Unix commands to progress through the game's narrative.
- Game Logic: Modify
backend/server.js(ptyProcess.onData). - Terminal Environment: Adjust
container/Dockerfileandcontainer/entrypoint.sh. - MOTD: Edit
container/your_motd_file.txt. - UI/Animations: Modify
frontend/js/animations.js,frontend/main.js,frontend/index.htmlCSS.
Project Chimera prioritizes security through Docker's isolation: ephemeral, read-only containers, tmpfs for home directories, network isolation, dropped Linux capabilities, and hardened file permissions. While the Node.js backend requires Docker daemon access, user interactions are strictly confined to their individual sandboxes.
MIT License