105 lines
3.7 KiB
Markdown
105 lines
3.7 KiB
Markdown
# 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/
|
||
|