Torollo — Backend Systems Lab

The Packet Tracer of backend engineering. Build architectures on a canvas where every node is a real Docker container on your machine — then follow guided roadmaps that grade each step against the actual state of your system.

Drawing boxes is easy; plenty of tools do it. Torollo is different in one specific way: when you draw a link, a real firewall rule is written; when you add a database, a real database starts; and when a roadmap step says "traffic from the public subnet must not reach Postgres", Torollo checks it by probing your live containers — not by comparing your answer to a diagram. You can't bluff it, and that's the point.

---

Quick Start

Docker must be running. Then, without cloning or installing anything permanently:

npx torollo start

Open the app, create a project, and hit Learning in the topbar — the best first contact with Torollo is a guided roadmap, not an empty canvas. Start with Deploy a resilient three-tier app: it walks you from a single web server to a load-balanced, firewalled, database-backed architecture in ten validated steps.

---

Guided, auto-graded roadmaps

The learning engine is what Torollo is really about. A roadmap is a sequence of steps — instructions, progressive hints, a solution if you're stuck — and every step is closed by validators that assert against the real state of your lab:

• container status and ASG replica counts,
• SQL schemas and data, MongoDB collections, Redis keys,
• network reachability and firewall restrictions between subnets,
• HTTP availability and response content.

A green check means your architecture actually does what the step asked. A red one tells you what was expected and what was observed instead — reading that gap is where the learning happens.

Current catalogue (English and French):

Roadmap	Difficulty	~Time	You practice
Deploy a resilient three-tier app	intermediate	40 min	Load balancing, security groups, private subnets, autoscaling
Cache-aside with Redis	intermediate	30 min	Caching strategy, TTLs, invalidation, measuring hit rates
Workers & the Redis job queue	intermediate	40 min	Async decoupling, queues, scaling workers under load, poison messages

Roadmaps are plain JSON — no code. The format is open and documented in the Roadmap Authoring Reference; drop a valid file into roadmaps/ and it appears in the catalogue. Community-authored roadmaps are very welcome. The validation HTTP API is documented in learning-api.md.

---

What you can put on the canvas

Every node maps 1:1 to a real Docker container running locally.

• Compute
  • Ubuntu Server — a Linux container with a native web terminal in your browser (WebSockets + xterm.js).
  • Auto Scaling Group — define a template, scale replicas up and down instantly.
• Data
  • PostgreSQL — with a built-in explorer for schemas, tables, and live SQL.
  • MongoDB — with an explorer for collections and JSON queries.
  • Redis — with an explorer for keys and native CLI commands.
• Messaging
  • RabbitMQ — message broker with management UI access.
• Networking & security
  • VPC & Subnets — isolated network boundaries backed by real Docker bridge networks.
  • Security Groups — visual inbound/outbound rules, enforced as actual iptables rules inside the containers.
  • Load Balancer (Nginx) — upstream configuration generated from the nodes you wire to it.
  • NAT Gateway — outbound access for private subnets via real ip_forward and MASQUERADE routing.

Beyond the nodes themselves: a traffic simulator to watch requests flow through your topology, root web terminals into any container, and clickable localhost shortcuts that appear when your firewall rules actually allow the traffic.

---

Self-Hosting & Network Exposure

By default, the Torollo API binds to 127.0.0.1 and only accepts cross-origin requests from local origins (localhost, 127.0.0.1, [::1]). Other machines on your network cannot reach it, and no configuration is needed for normal use.

To access Torollo from another machine (e.g. a home lab server), opt in explicitly:

TOROLLO_HOST=0.0.0.0 TOROLLO_ALLOWED_ORIGINS=http://<your-lan-ip>:23232 npx torollo start

• TOROLLO_HOST — address the API binds to (default 127.0.0.1; set to 0.0.0.0 to listen on all interfaces).
• TOROLLO_ALLOWED_ORIGINS — comma-separated list of exact extra origins allowed to call the API from a browser (the address you type into the browser, e.g. http://192.168.1.5:23232).

⚠️ Warning: Torollo has no authentication. Exposing it gives everyone on the network terminal access to its containers and control over Docker on your machine. Only do this on a trusted network, or put it behind an authenticating reverse proxy.

---

Architecture

• Backend — Node.js, Express, TypeScript, Socket.IO, Dockerode. The backend is the supervisor: it drives the local Docker daemon, compiles your visual topology into real iptables rules applied inside the containers, and persists state in ~/.torollo/projects.json. Every node image must ship with iptables and iproute2 — see Required tooling inside every node image.
• Frontend — React, TypeScript, Vite, React Flow. Renders the canvas, node inspectors, database explorers, the roadmap player, and xterm.js terminals.

---

Contributing

• Write a roadmap — the highest-leverage contribution, and it's JSON only. Start from the format reference.
• Add a node type — follow the step-by-step adding-a-node guide.
• Everything else — see CONTRIBUTING.md. Ideas for new directions (observability nodes, exporting a topology to IaC, …) are best opened as an issue first.

---

Philosophy

Everything runs locally, and the core is MIT-licensed — that's permanent, not a launch promise.

• No cloud credentials, no remote infrastructure created or billed.
• Every node on the canvas corresponds exactly to a live Docker container on your machine.
• Torollo is educational by design: not an AWS clone, not a production orchestration tool — a lab where system design becomes tangible because it actually executes.