diff --git a/Exam/README.md b/Exam/README.md new file mode 100644 index 0000000..737a5bc --- /dev/null +++ b/Exam/README.md @@ -0,0 +1,104 @@ +# Karel Robot Simulator + +**Live Demo:** https://phenomenal-starburst-ce7fd5.netlify.app/ + +--- + +## 1. Overview + +The **Karel Robot Simulator** is a static, browser-based educational tool that lets you: + +- **Write** Karel programs using parentheses & semicolons (`move()`, `turnLeft()`, `pickBeeper()`, `putBeeper()`, `if(...) {…}`, `while(...) {…}`). +- **Run** your code step-by-step or **stop** it mid-execution. +- **Visualize** the robot, walls, and beepers on an ASCII map. +- **Edit** the world manually or **upload** a `.txt/.kw` map file. +- **Consult** a stand-alone user manual at any time. + +--- + +## 2. Hosting & Container Architecture + +- **Public Cloud:** Netlify (static site + CDN + HTTPS via Let’s Encrypt). +- **Containerized Local Deploy:** + - **Dockerfile** builds an Nginx container serving your site on port 80. + - **docker-compose.yml** can orchestrate multiple services (e.g. Redis). +- **Maintenance Mode:** + - `maintenance/` folder holds a static “Site Under Maintenance” page. + - `enable-maintenance.sh` / `disable-maintenance.sh` swap your root content to toggle maintenance. +- **Continuous Deploy:** via Netlify CLI. +- **No Volumes / Kubernetes**. +- **DataBase** done automatically via the Netlify website. + +--- + +## 3. File & Directory Layout + +├─ Dockerfile # Builds Nginx image serving ./index.html and ./manual.html +├─ docker-compose.yml # multi-service compose (karel-simulator + Redis) +├─ netlify.toml # Netlify config: publish directory, redirects, maintenance rules +├─ start-app.sh # docker-compose up -d; shows container status on http://localhost:8080 +├─ stop-app.sh # docker-compose down; stops all compose services +├─ prepare-app.sh # docker build -t karel-simulator . +├─ remove-app.sh # docker rm/rmi; cleans up containers & image +├─ enable-maintenance.sh # deploys the static maintenance page to Netlify +├─ disable-maintenance.sh # reverts to your normal site content on Netlify +├─ maintenance/ # static maintenance-mode files (e.g. index.html, CSS) +│ └─ index.html +├─ index.html # Main simulator UI +├─ manual.html # Stand-alone user manual +├─ README.md # This documentation + +--- + +## 4. How to View & Use + +### On Netlify +```bash +export NETLIFY_AUTH_TOKEN="" +netlify login # needed once to login to your netlify +netlify link # will use the token instead of prompting you +netlify deploy --prod --dir=. + +1. **Browse** to https://phenomenal-starburst-ce7fd5.netlify.app/ +2. **Write** your Karel code; click **Compile & Run** or **Stop**. +3. **Edit Map** or **Upload Map File** to define custom worlds. +4. **Consult Manual** opens `manual.html` in a new tab. + +### Locally via Docker + +1. **Build** the Docker image: +```bash +./prepare-app.sh +Start the container(s): +./start-app.sh +- Your simulator is live at http://localhost:8080/. +Stop when finished: +./stop-app.sh +Cleanup image & containers: +./remove-app.sh + +## 5. Maintenance-Mode Scripts +enable-maintenance.sh + +Pushes the contents of /maintenance as your root on Netlify, showing a “Site Under Maintenance” page. + +disable-maintenance.sh + +Restores the live simulator (index.html/manual.html) as the root content. + +You can run these anytime via the Netlify CLI, provided you have your NETLIFY_SITE_ID and NETLIFY_AUTH_TOKEN in your environment. + +## 6. Execution Conditions +Docker Tools (Engine, BuildKit or legacy builder, and Compose plugin) installed. + +Netlify CLI authenticated (netlify login) if you run the maintenance scripts or deploy from Docker. + +Scripts should be run from the project root containing the Dockerfile and HTML files. + +## External References +Karel Format: https://karel.sourceforge.net/doc/html_mono/karel.html + +Netlify Docs: https://docs.netlify.com/ + +Docker & Nginx: https://docs.docker.com/, https://nginx.org/ + diff --git a/Exam/docker-compose.yml b/Exam/docker-compose.yml index a04527d..f8b8ddf 100644 --- a/Exam/docker-compose.yml +++ b/Exam/docker-compose.yml @@ -1,14 +1,18 @@ +version: "3.8" + services: - simulator: - build: . - image: karel-simulator + karel-simulator: + build: + context: . + dockerfile: Dockerfile container_name: karel-simulator ports: - "8080:80" restart: unless-stopped - redis: + karel-redis: image: redis:alpine container_name: karel-redis + ports: + - "6379:6379" restart: unless-stopped - diff --git a/Exam/start-app.sh b/Exam/start-app.sh index b0c7d93..6e6134b 100755 --- a/Exam/start-app.sh +++ b/Exam/start-app.sh @@ -1,7 +1,7 @@ #!/usr/bin/env bash set -e -# 1) Clean up any existing containers (manual or compose) +# 🧹 1) Clean up any existing containers for NAME in karel-simulator karel-redis; do if docker ps -a --format '{{.Names}}' | grep -q "^${NAME}\$"; then echo "🛑 Removing existing container '${NAME}'..." @@ -9,12 +9,14 @@ for NAME in karel-simulator karel-redis; do fi done -# 2) (Re)start both services in detached mode +# 🚀 2) (Re)start both services in detached mode echo "🚀 Starting multi-container application..." -docker compose up -d +# instead of: docker compose up -d +docker-compose up -d -# 3) Status +# ✅ 3) Show status +echo echo "✅ All containers are up:" -docker ps --filter "name=karel" --format " • {{.Names}} ({{.Image}}) → {{.Ports}}" -echo "" +docker ps --filter "name=karel-" --format " • {{.Names}} ({{.Image}}) → {{.Ports}}" +echo echo "🌐 Simulator: http://localhost:8080/"