Skip to content

Pixel Place API

Status

Active — optional backend used by Pixel Place for shared canvas state, quotas, and live updates.

Description

Small Node/Express API used by one or more frontends to share a single pixel board. Supports snapshot fetch, pixel placement, optimistic version checks, and SSE updates.

Base URLs

  • Production example: https://canvas.kiefermenard.com
  • Generic production pattern: https://your-nas.example.com
  • Local dev: http://127.0.0.1:3001

CORS

Set PLACE_ALLOWED_ORIGINS to exact, comma-separated origins allowed from browsers.

Example:

https://kiefermenard.com,https://friend.com

If unset, all origins are allowed (acceptable for local dev; not ideal for production).

API endpoints

Endpoint Purpose
GET /api/place/config Canvas dimensions and limits
GET /api/place/state Full board snapshot
POST /api/place/pixels Place 1..N pixels with quota and optional version check
GET /api/place/events SSE stream of delta updates (place events)
GET /health Basic health check

Key request/response behavior

  • POST /api/place/pixels uses:
  • userId (stable client ID, 8..128 chars, [a-zA-Z0-9_-]+)
  • expectedVersion (optional optimistic concurrency)
  • pixels list (c must be #RRGGBB)
  • Duplicate coordinates in one request are deduplicated (last wins).
  • Common responses:
  • 200 success with version, nextAllowedAt, quota remaining
  • 429 quota exceeded with retryAfterMs
  • 409 stale version conflict with latest version

Rate limits

POST /api/place/pixels is limited per IP by default (60 requests / 60s), controlled by:

  • PLACE_RATE_LIMIT_MAX
  • PLACE_RATE_WINDOW_MS

Environment variables

Variable Default Description
PLACE_PORT 3001 Listen port
PLACE_WIDTH 200 Canvas width
PLACE_HEIGHT 200 Canvas height
PLACE_COOLDOWN_SECONDS 10 Quota window length (seconds)
PLACE_MAX_PIXELS_PER_TURN 5 Max pixels per window per userId
PLACE_DATA_PATH ./server/data Directory containing place.json
PLACE_ALLOWED_ORIGINS empty CORS allowlist (empty = allow all)
PLACE_TRUST_PROXY unset Set to 1 behind reverse proxy
PLACE_RATE_WINDOW_MS 60000 IP rate-limit window
PLACE_RATE_LIMIT_MAX 60 Max POSTs per IP per window

Deployment (Leviathon / reverse proxy)

Production runs in Docker on the Synology (Leviathon) from /volume1/docker/personal-website-server/docker-compose.yml, with PLACE_TRUST_PROXY=1. Without it, rate limiting sees the Synology reverse proxy’s internal IP instead of the real client, so limits apply incorrectly. Set PLACE_ALLOWED_ORIGINS to the exact browser origins that may call the API (e.g. https://kiefermenard.com,https://www.kiefermenard.com). Public URL: https://canvas.kiefermenard.com (Cloudflare → Synology 443). See also projects/Self-Hosted-Services.

Watchtower: the API image is built locally, so the service carries a label so Watchtower skips it and does not error on registry lookups:

labels:
  com.centurylinklabs.watchtower.enable: "false"

(See projects/Self-Hosted-Services#watchtower-monitor-only.)

Known issues

  • None documented in this wiki yet.

Raw sources

  • raw/API.md