Skip to content

docs: update README and LAB with EC2 support details #44

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
gamaware merged 1 commit into from
Apr 14, 2026
Merged

docs: update README and LAB with EC2 support details #44

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions 10-databases/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines 46 to +50
Copy link

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Prerequisites list still implies Docker Desktop is required, but the doc now supports an EC2 (browser-only) path. Consider splitting prerequisites by environment (Local vs EC2) or rewording this section so EC2 readers don’t think they need Docker Desktop.

Copilot uses AI. Check for mistakes.

## 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
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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.
Copy link

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section introduces an EC2 quick start, but the README’s Cleanup section below still only shows running ./cleanup.sh (local). To keep the EC2 option reproducible end-to-end, add a brief EC2 cleanup note here (e.g., delete the CloudFormation stack).

Suggested change
**VisualizerURL** from the Outputs tab.
**VisualizerURL** from the Outputs tab. When you finish the lab,
delete the CloudFormation stack to clean up the EC2 deployment.

Copilot uses AI. Check for mistakes.

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.

Expand Down Expand Up @@ -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 |
Copy link

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The troubleshooting row advises waiting 5–10 minutes after CREATE_COMPLETE for Docker setup, but earlier the Quick Start says the stack completes in ~5–10 minutes (and LAB instructions suggest only a short extra wait after completion). Please make the timing guidance consistent to avoid confusion.

Suggested change
| EC2 page does not load | Stack still initializing | Wait 5-10 min after CREATE_COMPLETE for Docker setup |
| EC2 page does not load | Stack still initializing | Wait a few minutes after `CREATE_COMPLETE` for Docker setup |

Copilot uses AI. Check for mistakes.
| EC2 stack create fails | Learner Lab not started | Ensure the AWS indicator is green before creating the stack |

## Key Concepts

Expand All @@ -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
Expand Down
14 changes: 11 additions & 3 deletions 10-databases/visualizer/LAB-VISUALIZER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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 |
Expand All @@ -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 |
Copy link

Copilot AI Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The troubleshooting guidance says to wait 5–10 minutes after CREATE_COMPLETE, but earlier in the EC2 setup flow the stack creation itself is estimated at 5–10 minutes and then suggests waiting “another minute” if the page doesn’t load. Please align these so readers don’t get conflicting timing expectations (e.g., “wait a couple minutes after CREATE_COMPLETE” or similar).

Suggested change
| EC2 page does not load | Stack still initializing | Wait 5-10 min after CREATE_COMPLETE for Docker setup |
| EC2 page does not load | Stack still initializing | Wait a couple of minutes after CREATE_COMPLETE for Docker setup |

Copilot uses AI. Check for mistakes.
| EC2 stack create fails | Learner Lab not started | Ensure the AWS indicator is green before creating the stack |

## Key Concepts

Expand Down
Loading