From 9aa6e49791ba99e3b173e5fe77cdb664e3380c82 Mon Sep 17 00:00:00 2001 From: Alex Garcia Date: Mon, 13 Apr 2026 21:48:41 -0600 Subject: [PATCH] docs: update README and LAB with EC2 support details --- 10-databases/README.md | 34 +++++++++++------------ 10-databases/visualizer/LAB-VISUALIZER.md | 14 ++++++++-- 2 files changed, 28 insertions(+), 20 deletions(-) diff --git a/10-databases/README.md b/10-databases/README.md index b907520..820d31b 100644 --- a/10-databases/README.md +++ b/10-databases/README.md @@ -46,12 +46,15 @@ For optional CLI-based labs with MongoDB and Cassandra, see - **Docker Desktop** installed and running (includes Docker Compose) - A web browser (Chrome, Firefox, or Safari) - Basic SQL knowledge (SELECT, INSERT, UPDATE) -- No cloud account required for the main lab +- No cloud account required for local Docker; AWS Academy credentials + required for the EC2 option ## Architecture The visualizer connects to a live MySQL primary-replica cluster. Every button click and console query executes real SQL against real databases. +The same Docker Compose stack runs locally or on an EC2 instance via +CloudFormation. ```mermaid graph LR @@ -88,6 +91,7 @@ graph LR ├── visualizer/ # Main lab (interactive browser) │ ├── LAB-VISUALIZER.md # Step-by-step instructions (5 tasks) │ ├── docker-compose.yml # MySQL primary + replica + visualizer +│ ├── cloudformation.yaml # EC2 deployment (AWS Academy) │ ├── setup.sh / cleanup.sh # Start and stop environment │ ├── Dockerfile # Python API bridge image │ ├── server.py # API bridge (proxies SQL to MySQL) @@ -118,14 +122,21 @@ graph LR ## Quick Start +**Local (Docker Desktop):** + ```bash cd visualizer ./setup.sh ``` -Open [http://localhost:8081](http://localhost:8081). The visualizer -has three tabs (Replication, Consistency, Schema & Indexing) and a -SQL console at the bottom. Follow +Open [http://localhost:8081](http://localhost:8081). + +**EC2 (AWS Academy):** Upload `visualizer/cloudformation.yaml` to +CloudFormation. When the stack completes (~5-10 min), open the +**VisualizerURL** from the Outputs tab. + +The visualizer has three tabs (Replication, Consistency, Schema & +Indexing) and a SQL console at the bottom. Follow [LAB-VISUALIZER.md](visualizer/LAB-VISUALIZER.md) for the guided walkthrough. @@ -167,6 +178,8 @@ cd visualizer | Animation stuck | Previous operation running | Wait for it to finish or refresh the page | | Port 3306 in use | Local MySQL running | Stop local MySQL or change port in docker-compose | | Cassandra OOM crash | Not enough Docker memory | Allocate at least 4 GB RAM in Docker Desktop | +| EC2 page does not load | Stack still initializing | Wait 5-10 min after CREATE_COMPLETE for Docker setup | +| EC2 stack create fails | Learner Lab not started | Ensure the AWS indicator is green before creating the stack | ## Key Concepts @@ -186,19 +199,6 @@ cd visualizer | **Write concern** | How many nodes must acknowledge a write (MongoDB) | | **Consistency level** | How many replicas must respond for a read/write (Cassandra) | -## Presentation - -Interactive reveal.js presentation in `presentation/index.html`. -See `shared/presentation/README.md` for the template API reference. - -```bash -open presentation/index.html -``` - -31 slides with animated SVG diagrams, bilingual EN/ES toggle, -dark/light mode, interactive expandable cards, and official AWS -architecture icons. - ## How This Relates to Scalable Systems Design **Replication is the most common first step in scaling a relational diff --git a/10-databases/visualizer/LAB-VISUALIZER.md b/10-databases/visualizer/LAB-VISUALIZER.md index 302723a..4cf2aba 100644 --- a/10-databases/visualizer/LAB-VISUALIZER.md +++ b/10-databases/visualizer/LAB-VISUALIZER.md @@ -156,6 +156,7 @@ graph LR 10-databases/visualizer/ ├── LAB-VISUALIZER.md # This file (lab instructions) ├── docker-compose.yml # MySQL primary + replica + visualizer +├── cloudformation.yaml # EC2 deployment template (AWS Academy) ├── setup.sh # Start environment and configure replication ├── cleanup.sh # Tear down all containers and volumes ├── Dockerfile # Python API bridge image @@ -171,9 +172,9 @@ graph LR ### Step 1.1: Verify the cluster -After running `./setup.sh`, open -[http://localhost:8081](http://localhost:8081). The sidebar on the -right shows live database state: +Open the visualizer in your browser (`http://localhost:8081` for local +setup, or the **VisualizerURL** from CloudFormation Outputs for EC2). +The sidebar on the right shows live database state: - **IO Thread / SQL Thread**: Both should show `Yes` (replication active) @@ -458,10 +459,15 @@ custom indexes). ## Cleanup +**Local:** + ```bash ./cleanup.sh ``` +**EC2:** Delete the `lab10-visualizer` CloudFormation stack in the AWS +Console (see [EC2 Cleanup](#ec2-cleanup) above). + ## Troubleshooting | Issue | Cause | Fix | @@ -471,6 +477,8 @@ custom indexes). | Replica shows `--` in sidebar | Replication not configured | Re-run `./setup.sh` | | EXPLAIN shows `rows: 1` | Table stats stale | Run `ANALYZE TABLE access_log;` in the console | | Animation stuck | Previous operation still running | Wait for it to finish or refresh the page | +| EC2 page does not load | Stack still initializing | Wait 5-10 min after CREATE_COMPLETE for Docker setup | +| EC2 stack create fails | Learner Lab not started | Ensure the AWS indicator is green before creating the stack | ## Key Concepts