LuaMicroservices/Readme.md

Handheld Devices

A microservices stack for managing handheld gaming device catalog data: Lua API and worker, Deno/Alpine.js frontend, PostgreSQL, and Redis.

Architecture

Service	Tech	Port	Description
API	Lua 5.4	8080	REST API for devices CRUD
Worker	Lua 5.4	-	Consumes events from Redis queue
Frontend	Deno + Alpine.js	8090	Web UI backed by Oak
Postgres	15-alpine	5432	Primary data store
Redis	7-alpine	6379	Event queue and caching

Quick Start

Prerequisites

• Docker and Docker Compose
• Lua 5.4 + LuaRocks (for local dev/testing)
• Deno 2.x (for local frontend dev)

Run with Docker Compose

cp .env.example .env
# Edit .env if needed (e.g. DB_PASSWORD)

make install-deps  # optional: LuaRocks + Deno deps for local dev
make dev

• API: http://localhost:8080
• Frontend: http://localhost:8090
• Health: http://localhost:8080/health/ready

Stop

make down

Development

Install all dependencies for local development (LuaRocks packages and Deno cache):

make install-deps

API (devices-api)

cd devices-api
make deps    # luarocks install
make test    # unit tests (busted)
make lint    # luacheck
make run     # run locally (needs Postgres + Redis)

Worker (devices-worker)

cd devices-worker
make deps
make lint
make run     # needs Postgres + Redis

Frontend

cd frontend
make run     # or: deno task start (with watch)
make lint    # deno check

Makefile Reference

From project root:

Target	Description
make install-deps	Install LuaRocks + Deno deps for local dev
make dev	Start all services
make down	Stop all services
make build	Build Docker images
make test	Run API unit tests
make lint	Luacheck + Deno check
make logs	Follow API logs
make logs-worker	Follow worker logs
make init-db	Run DB migrations manually
make shell-postgres	psql in Postgres container
make status	Container status

API Endpoints

Method	Path	Description
GET	/devices	List devices (paginated)
POST	/devices	Create device
GET	/devices/:id	Get device
PUT	/devices/:id	Update device
DELETE	/devices/:id	Delete device
GET	/health/ready	Readiness (DB + Redis)
GET	/health/live	Liveness

Deployment

• Kubernetes: helm lint k8s/handheld-devices
• CI: See .github/workflows/ci.yml (lint, build, unit tests, helm lint)

Docker Swarm

Use compose.swarm.yml to deploy to Docker Swarm. Postgres is pinned to a single node (via label) so its volume stays on one node.

Label the node that will run Postgres before deploying:

docker node ls
docker node update --label-add db=true <NODE_ID>

Then deploy:

docker swarm init   # if not already a swarm manager
make swarm-deploy

Target	Description
make swarm-build	Build and tag images for Swarm
make swarm-deploy	Build images and deploy stack
make swarm-down	Remove stack from Swarm

Environment

See .env.example for configuration. Key variables:

• DB_* – PostgreSQL connection
• REDIS_* – Redis connection
• API_URL – API URL used by the frontend (for browser requests)