Ilia Denisov
0e3e3b6c90
- .gitea/workflows/ci.yaml: test on PR/push to master, deploy on push to master - deploy/docker-compose.yml: 15-puzzle container on the edge network with a persistent data volume - Dockerfile: create /data owned by app for the DATA_FILE volume - README: document deployment, required Actions secrets/variables, and persistence
79 lines
3.8 KiB
Markdown
79 lines
3.8 KiB
Markdown
# 15 Puzzle game with Go
|
|
|
|
🚀 [Play in Telegram](https://t.me/puzzle_15_bot?startapp).
|
|
Game has [simple rules](https://en.wikipedia.org/wiki/15_puzzle).
|
|
|
|
## Description
|
|
|
|
The intentions of the project is to create a simple proof-of-concept demonstrating that a [Telegram Mini App](https://core.telegram.org/bots/webapps) can be developed with Go and [WebAssembly](https://go.dev/wiki/WebAssembly).
|
|
|
|
✨ Graphics are made with [Ebitengine](https://github.com/hajimehoshi/ebiten).
|
|
|
|
Basic "features" include: a splash screen, game move sound, a switchable silent mode without moves count,
|
|
a players' rating table, a congratulations screen for achieving 1st place,
|
|
a pin-code protected game statistics screen,
|
|
and backend API requests secured through [data validation](https://core.telegram.org/bots/webapps#validating-data-received-via-the-mini-app).
|
|
|
|
## Running game
|
|
|
|
Local gameplay can be initiated using the following command:
|
|
|
|
```shell
|
|
go run ./cmd/ui
|
|
```
|
|
|
|
A fully functional Mini App requires a web server.
|
|
You can use [`Dockerfile`](Dockerfile) to build a Docker Image
|
|
containing all necessary artifacts: the server binary, the WebAssemply (wasm) binary, and html page.
|
|
Certain environment variables should be set for the server to start:
|
|
|
|
| Env | Description |
|
|
| - | - |
|
|
| **`BOT_TOKEN`** | Telegram Bot [API Token](https://core.telegram.org/bots/tutorial). |
|
|
| **`DATA_FILE`** | Path to the file where games data will be stored. |
|
|
| **`ACCESS_CODE`** | Pin-code to access the Statistics Screen. |
|
|
| **`PROJECT_LINK`** | URL to the project's source code. |
|
|
| `SERVER_PORT` | Port for the server to listen for API requests, defaulting to `8080` if not set. |
|
|
| `CONTEXT_ROOT` | Server requests URI root path, defaulting to `/` if not set. |
|
|
| `STATIC_DIR` | Directory where static files are located, defaulting to the current directory if not set. |
|
|
|
|
## Deployment
|
|
|
|
The repository ships a [Gitea Actions](https://docs.gitea.com/usage/actions/overview)
|
|
workflow ([`.gitea/workflows/ci.yaml`](.gitea/workflows/ci.yaml)) that runs the
|
|
server test suite on every pull request to `master`, and on every push to
|
|
`master` additionally rebuilds the Docker image and (re)deploys the container on
|
|
the host Docker daemon through [`deploy/docker-compose.yml`](deploy/docker-compose.yml).
|
|
|
|
The deploy job runs in host mode: it builds the image locally (no registry) and
|
|
recreates the `15-puzzle` container attached to the external `edge` Docker
|
|
network, so a host reverse proxy can route to `15-puzzle:8080`.
|
|
|
|
### Required Actions secrets and variables
|
|
|
|
Configure these under the repository's *Settings → Actions*:
|
|
|
|
| Kind | Name | Example / note |
|
|
| - | - | - |
|
|
| Secret | `BOT_TOKEN` | Telegram Bot API token. |
|
|
| Secret | `ACCESS_CODE` | Pin-code for the Statistics Screen. |
|
|
| Variable | `PROJECT_LINK` | URL to the project's source code. |
|
|
| Variable | `DATA_FILE` | `/data/data.json` (lives on the persistent volume). |
|
|
| Variable | `SERVER_PORT` | `8080`. |
|
|
| Variable | `CONTEXT_ROOT` | `/`. |
|
|
|
|
`STATIC_DIR` is intentionally left unset: the static assets (HTML, `game.wasm`,
|
|
`wasm_exec.js`) are baked into the image and served from the working directory.
|
|
|
|
### Persistence
|
|
|
|
Game data is stored on the named Docker volume `15-puzzle-data` mounted at
|
|
`/data`, so player ratings survive container recreation. The image creates
|
|
`/data` owned by the unprivileged `app` user so the volume is writable.
|
|
|
|
## Credits
|
|
|
|
- [Ebitengine](https://github.com/hajimehoshi/ebiten) game engine by Hajime Hoshi.
|
|
- Font by [VileR](http://int10h.org) and [fly_indiz](http://old-dos.ru/index.php?page=files&mode=files&do=show&id=102798).
|
|
- ASCII Gopher by [gheimifurt](https://www.reddit.com/r/golang/comments/xdxb9a/gopher_ascii_art_for_bashrc/).
|