Skip to content
ArgonetDevStudioPublic

About

Find out the daily lunch menu effortlessly.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

Foodbox

Foodbox downloads the Eisodosirak lunch menu image, parses it with Naver Clova OCR, keeps the result in a file database, renders a Svelte calendar, and sends daily Slack notifications.

Production runs as two small containers:

  • one non-root Go application containing the API, scheduler, OCR pipeline, file store, and compiled Svelte assets;
  • Caddy as the only host-facing service, providing automatic HTTPS and reverse proxying to the application.

Requirements

  • Go 1.26.10 (the toolchain pinned by CI and release workflows; go.mod declares Go 1.26.0 as the module minimum)
  • Node.js 24 and npm
  • Docker with Docker Compose v2 for container testing or deployment

Local development

Backend tests do not require production credentials:

cd backend
go test ./...

Build the frontend:

cd front
npm ci
npm run build

The Go process reads configuration only from its environment; it does not load .env itself. Copy .env.example to the repository-local .env, replace every placeholder outside version control, export that file in the shell, and then run the application from backend/. When running from that directory, make sure the database and static-directory variables resolve to the repository's db/ and front/dist/ directories.

cd backend
set -a
source ../.env
set +a
DB_FILE_DIR=../db STATIC_DIR=../front/dist go run ./cmd/foodbox

For a production-like local build that bundles the frontend and uses the image runtime defaults:

docker build --tag foodbox-local .
docker run --rm --env-file .env --publish 8080:8080 \
  --env DB_FILE_DIR=/data --env STATIC_DIR=/app/static \
  --volume foodbox-local-data:/data foodbox-local

Then check the readiness endpoint and menu API:

curl --fail http://127.0.0.1:8080/healthz
curl --fail http://127.0.0.1:8080/api/menu

Verification

Run the full backend verification from backend/:

go test ./...
go test -race ./...
go vet ./...
go build ./cmd/foodbox

Run the frontend build from front/:

npm ci
npm run build

The Go tests deliberately pin behavior that users can observe. They cover the file-database representation and upsert order, exact public API JSON, Slack payload and Korean message text, 09:00 Asia/Seoul scheduling, startup/schedule overlap, OCR date edge cases, and complete golden-menu output for the retained OCR fixtures. Run both the ordinary and race suites before changing persistence, crawling, OCR, API, scheduling, or Slack behavior.

Container and deployment changes should additionally render Compose, build the Linux AMD64 image, and smoke-test /healthz, /, and /api/menu. CI performs the clean-checkout backend, frontend, and container builds before a production image is published.

Configuration

Do not put credentials in source files, Docker images, commands, issue comments, or GitHub repository variables. The table names the variables only; secret values are intentionally omitted.

Variable Required Purpose
CLOVA_URL Yes Clova OCR invocation endpoint
CLOVA_SECRET_KEY Yes Clova OCR credential
SLACK_TOKEN Yes Incoming-webhook path secret, not a bot OAuth token
SLACK_CHANNEL Yes Slack destination channel
CRAWL_URL No Eisodosirak menu board URL
SLACK_URL No Slack webhook base URL
SLACK_USERNAME No Display name used by the Slack message
ADMIN_TOKEN No Internal management API credential; an empty value disables those routes
SERVER_PORT No Application listen port
DB_FILE_DIR No Directory containing db.json and metadata.json
STATIC_DIR No Compiled Svelte asset directory
TZ No Runtime timezone; production scheduling uses Seoul time

Production keeps application configuration in the server-side .env. The deployment script never replaces this file and restricts its permissions. It creates a separate .deploy.env containing only deployment metadata needed by Compose. FOODBOX_IMAGE and DOMAIN belong to that generated deployment file, not to the application secret store.

HTTP API

Public routes:

Method Route Purpose
GET /healthz Verify that the file store is readable and writable
GET /api/menu Return all menus, newest first
GET /api/menu/today Return today's menu

Management routes implemented by the application:

Method Route Purpose
POST /api/crawl Download, OCR, and persist the current menu
POST /api/upload Parse one multipart file upload, limited to 10 MB
POST /api/menu/manual Validate and upsert one menu from an ISO date and ordered menu list
POST /api/slack/notify Send today's notification immediately

Management routes require ADMIN_TOKEN through a bearer authorization header or X-Admin-Token. Production Caddy returns 404 for them before requests reach the application, so possessing the token does not expose them on the public internet. Add a separately authenticated operator path before changing that edge policy.

For local development, or when the application port is published, register or correct one date manually with an authenticated JSON request:

curl --fail --request POST http://127.0.0.1:8080/api/menu/manual \
  --header "Authorization: Bearer $ADMIN_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"date":"2026-10-01","menus":["콩나물국","갈비찜","미역줄기볶음","무생채나물무침","콩조림","아삭이장무침","꼬마김치"]}'

Production Compose exposes the app port only to the Compose network, and the public Caddy edge intentionally blocks this management route. Run the same request inside the app container instead:

ADMIN_TOKEN_VALUE='replace-with-server-admin-token'
docker compose --env-file .deploy.env exec -T app wget -qO- \
  --header="Authorization: Bearer ${ADMIN_TOKEN_VALUE}" \
  --header='Content-Type: application/json' \
  --post-data='{"date":"2026-10-01","menus":["콩나물국","갈비찜","미역줄기볶음","무생채나물무침","콩조림","아삭이장무침","꼬마김치"]}' \
  http://127.0.0.1:8080/api/menu/manual

The date must be a valid YYYY-MM-DD value and menus must contain at least three non-empty strings. Repeating a date replaces only that date; existing dates remain unchanged.

Responses use the {status,error,data} envelope and the menu fields consumed by the frontend. Error responses use the corresponding HTTP status. The All state-changing management routes require POST.

Persistence and scheduling

  • db.json stores dates as [year,month,day] alongside menus and valid. Disk records are oldest first; /api/menu is newest first.
  • Deployment snapshots preserve legacy records with "menus": null, which the Go store reads as a nil slice; non-array or non-string menu values remain invalid, and new writes use arrays.
  • metadata.json persists the last successfully processed image hash, avoiding duplicate OCR work across restarts. A matching hash is skipped only while the database still contains today's menu, so missing state can repair itself.
  • Writes use a unique temporary file, file and directory sync, and atomic replacement. Only one application instance may own the volume.
  • Startup refresh runs after the HTTP server becomes ready and does not block readiness on vendor or Clova availability.
  • Slack notification runs once daily at 09:00 Seoul time. Startup refresh and daily notification cannot overlap; a 09:00 tick during refresh is queued and sent after refresh completes.

CI/CD

  • .github/workflows/ci.yml tests Go, validates deployment operations, builds Svelte, and builds the Linux AMD64 container for pull requests targeting main and manual dispatches. Commits pushed to dev do not start CI.
  • .github/workflows/deploy.yml starts on every push to main. Its own release verification must pass before it builds and publishes the GHCR image, and only the exact published digest is passed to the server deployment job.
  • .github/workflows/rollback.yml is a manually dispatched rollback from main to the stored previous successful Go release.

The Oracle VM never runs Go, Node, or Docker image builds during normal deployment. It pulls an immutable digest, backs up the file database, starts the stack, and accepts the release only after Compose health checks and the public HTTPS health check succeed.

Application credentials are never sent by the workflow. They remain in the Oracle VM's protected .env. The GitHub production Environment contains only the SSH deployment secrets and optional DEPLOY_PATH / PUBLIC_URL variables. The GHCR package must either be publicly readable or the VM must already be logged in with a narrowly scoped read-only package credential.

A push to main starts the deploy workflow whether it came from a merged PR or a direct push. PR review and approval are enforced only by the repository's branch ruleset; Actions does not impose them. Configure a required reviewer on the GitHub production Environment to hold the server job for explicit approval after verification and image publication. The server locks concurrent operations, snapshots the database, pulls immutable images, and accepts a release only after runtime, API, UI, database, and single-writer checks pass.

If no previous successful Go release exists, a failed deployment restores the exact stopped-state database and the original configuration-existence state, then remains stopped. Later deployment failures restore and verify the Go release that was active when deployment started. See deploy/README.md for the operation exit-code contract.

After two successful deployments, the Roll back production workflow can be manually dispatched from main to restore and verify the previously successful digest. Never run docker compose down -v because the Caddy volumes contain certificate state.

About

Find out the daily lunch menu effortlessly.

Resources

Stars

0 stars

Watchers

1 watching

Forks

Contributors

Languages