Write project README with self-hosted Gitea deployment options
This commit is contained in:
187
README.md
Normal file
187
README.md
Normal file
@@ -0,0 +1,187 @@
|
|||||||
|
# Conway's Game of Life (Vanilla JS)
|
||||||
|
|
||||||
|
A polished, static, self-hosting-friendly web app implementing Conway’s Game of Life with HTML5 Canvas, vanilla JavaScript, and CSS.
|
||||||
|
|
||||||
|
This project is designed for a self-hosted Gitea workflow and can be served from any static hosting target (Nginx, Caddy, pages-style branch, or CI-based copy/deploy).
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- Correct Conway’s Game of Life rules with separate current/next generation buffers
|
||||||
|
- Canvas-based renderer with responsive board sizing
|
||||||
|
- Play, pause, single-step, clear, randomize
|
||||||
|
- Adjustable simulation speed and zoom (cell size)
|
||||||
|
- Click-and-drag painting and erasing
|
||||||
|
- Preset patterns:
|
||||||
|
- Block
|
||||||
|
- Blinker
|
||||||
|
- Toad
|
||||||
|
- Beacon
|
||||||
|
- Glider
|
||||||
|
- Lightweight spaceship (LWSS)
|
||||||
|
- Pulsar
|
||||||
|
- Gosper glider gun
|
||||||
|
- Pattern stamping workflow
|
||||||
|
- Generation counter and live-cell counter
|
||||||
|
- Boundary mode toggle (fixed edges vs toroidal wrapping)
|
||||||
|
- Gridline toggle
|
||||||
|
- Import/export board state (JSON + compact text)
|
||||||
|
- Keyboard shortcuts and integrated help panel
|
||||||
|
- About section and accessible, semantic UI
|
||||||
|
- Light/dark theme toggle
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
|
||||||
|
```text
|
||||||
|
.
|
||||||
|
├── .gitea/
|
||||||
|
│ └── workflows/
|
||||||
|
│ └── ci.yml
|
||||||
|
├── js/
|
||||||
|
│ ├── app.js # UI/controller wiring and app lifecycle
|
||||||
|
│ ├── engine.js # Simulation engine and state transitions
|
||||||
|
│ ├── patterns.js # Preset pattern library
|
||||||
|
│ ├── renderer.js # Canvas drawing logic
|
||||||
|
│ └── utils.js # Small helper utilities
|
||||||
|
├── index.html
|
||||||
|
├── style.css
|
||||||
|
└── README.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## Screenshots
|
||||||
|
|
||||||
|
> Add screenshots in your repo and link them here.
|
||||||
|
|
||||||
|
- `docs/screenshot-main.png` (placeholder)
|
||||||
|
- `docs/screenshot-patterns.png` (placeholder)
|
||||||
|
|
||||||
|
## Controls & Shortcuts
|
||||||
|
|
||||||
|
### Mouse / UI
|
||||||
|
|
||||||
|
- Click and drag on canvas to draw/erase cells
|
||||||
|
- Use **Stamp Selected** to place a preset pattern
|
||||||
|
- Use speed and cell-size sliders to tune simulation
|
||||||
|
|
||||||
|
### Keyboard
|
||||||
|
|
||||||
|
- `Space`: Play / Pause
|
||||||
|
- `S`: Step one generation
|
||||||
|
- `C`: Clear board
|
||||||
|
- `R`: Randomize board
|
||||||
|
- `G`: Toggle gridlines
|
||||||
|
- `W`: Toggle wrapping mode
|
||||||
|
- `+` / `-`: Zoom in/out (cell size)
|
||||||
|
- `?`: Toggle help panel
|
||||||
|
- `Esc`: Exit stamp mode
|
||||||
|
|
||||||
|
## Local Development
|
||||||
|
|
||||||
|
No build step is required.
|
||||||
|
|
||||||
|
1. Clone your repository:
|
||||||
|
```bash
|
||||||
|
git clone https://gitea.nalakath.org/<your-user>/<your-repo>.git
|
||||||
|
cd <your-repo>
|
||||||
|
```
|
||||||
|
2. Serve statically from the repo root, for example:
|
||||||
|
```bash
|
||||||
|
python3 -m http.server 8080
|
||||||
|
```
|
||||||
|
3. Open `http://localhost:8080`.
|
||||||
|
|
||||||
|
## Push to Self-hosted Gitea
|
||||||
|
|
||||||
|
If this folder is not already linked to your Gitea repo:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git init
|
||||||
|
git add .
|
||||||
|
git commit -m "Initial Conway's Game of Life web app"
|
||||||
|
git branch -M main
|
||||||
|
git remote add origin https://gitea.nalakath.org/<your-user>/<your-repo>.git
|
||||||
|
git push -u origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
## Deployment Options (Self-hosted Gitea-first)
|
||||||
|
|
||||||
|
### 1) Serve static files directly with Nginx or Caddy
|
||||||
|
|
||||||
|
Deploy by copying/checkout repo contents to a web root.
|
||||||
|
|
||||||
|
**Nginx example (subdomain):**
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name life.example.com;
|
||||||
|
root /srv/www/conway_gameoflife;
|
||||||
|
index index.html;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
try_files $uri $uri/ /index.html;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Caddy example (subdomain):**
|
||||||
|
|
||||||
|
```caddyfile
|
||||||
|
life.example.com {
|
||||||
|
root * /srv/www/conway_gameoflife
|
||||||
|
file_server
|
||||||
|
try_files {path} /index.html
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2) Deploy from a pages-style branch (if your Gitea setup supports it)
|
||||||
|
|
||||||
|
Keep app files in a dedicated branch (for example `pages`) and configure your Gitea pages/static serving integration to publish that branch.
|
||||||
|
|
||||||
|
Example flow:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout --orphan pages
|
||||||
|
git rm -rf .
|
||||||
|
# copy or keep only static site files
|
||||||
|
git add .
|
||||||
|
git commit -m "Publish static site"
|
||||||
|
git push -u origin pages
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3) Deploy via Gitea Actions to web root or object storage
|
||||||
|
|
||||||
|
Use CI to run checks and then copy static files to your internal target (SSH, rsync, NFS mount, MinIO/S3-compatible object storage, etc.).
|
||||||
|
|
||||||
|
Included workflow: `.gitea/workflows/ci.yml` with basic sanity checks.
|
||||||
|
|
||||||
|
You can extend it to:
|
||||||
|
|
||||||
|
- upload `index.html`, `style.css`, and `js/` to a server path
|
||||||
|
- sync to object storage
|
||||||
|
- update a reverse-proxy-served folder atomically
|
||||||
|
|
||||||
|
## Subpath Hosting Notes
|
||||||
|
|
||||||
|
This app uses only relative asset paths (`./style.css`, `./js/app.js`), so it works from:
|
||||||
|
|
||||||
|
- root path: `https://example.com/`
|
||||||
|
- subpath: `https://example.com/apps/life/`
|
||||||
|
|
||||||
|
Just ensure `index.html`, `style.css`, and `js/` remain together.
|
||||||
|
|
||||||
|
## Optional CI Notes
|
||||||
|
|
||||||
|
The provided workflow checks:
|
||||||
|
|
||||||
|
- required files exist
|
||||||
|
- JavaScript syntax is valid (`node --check`)
|
||||||
|
|
||||||
|
Add stricter linting if desired in your own environment.
|
||||||
|
|
||||||
|
## Future Improvements
|
||||||
|
|
||||||
|
- Pattern rotation/mirroring before stamping
|
||||||
|
- RLE import/export
|
||||||
|
- Infinite-grid viewport mode with panning
|
||||||
|
- Touch-specific toolbar for mobile ergonomics
|
||||||
|
- Save/load presets in localStorage
|
||||||
Reference in New Issue
Block a user