Skip to content

Sample Apps Reference

Seven sample applications exercise the AppMecca platform end-to-end. Each lives in its own public GitLab repository; clone any of them and deploy in minutes.

GitLab group: gitlab.com/appmecca-sample-apps

The authoritative per-app list (with services, storage, and role descriptions) lives in sample_apps/README.md in the platform repo. This page pairs that list with deploy commands and feature-by-example cross-references aimed at platform users.

Quick reference

App Repo Scope PG Redis Drive Edge What it shows
hello-flask ↗ minimal — — — — Simplest possible AppMecca app
django-celery-tasks ↗ workers ✓ ✓ — — Celery workers from one image
recipe-cookoff ↗ showcase ✓ ✓ ✓ ✓ SvelteKit + React A/B comparison
two-newsrooms ↗ showcase ✓ — ✓ ✓ Wagtail news site + summariser
photogallery ↗ showcase ✓ ✓ — ✓ On-demand Pillow resize + edge caching
eventpass ↗ showcase ✓ ✓ — ✓ Ticketing + Beat-driven hold reaper
shortlink ↗ showcase ✓ ✓ — ✓ URL shortener + analytics

PG = the managed PostgreSQL database (database.enabled: true). Redis = the managed Redis cache (cache.enabled: true). Drive = shared filesystem across replicas (storage.drives + deploy[].drives). Edge = AppMecca edge-cache behaviours on the frontend SPA (deploy[].cache).

The apps

hello-flask

The minimal AppMecca app — one Flask container, one service, one health check. Use this as a template when starting a new app from scratch.

containers:
  - name: hello-flask
    dockerfile: Dockerfile
    context: .

deploy:
  - name: web
    container: hello-flask
    port: 5000
    health_check:
      path: /health

django-celery-tasks

Two services built from a single Docker image — the web service runs Django on port 8000, the worker service runs celery -A config worker with no port. Uses both the managed PostgreSQL database (via database.enabled) and the managed Redis cache (via cache.enabled) as the Celery broker.

containers:
  - name: django-celery-app
    dockerfile: Dockerfile
    context: .

deploy:
  - name: web
    container: django-celery-app
    port: 8000
    health_check:
      path: /health

  - name: worker
    container: django-celery-app
    command: "celery -A config worker -l info"

database:
  enabled: true

redis:
  enabled: true

recipe-cookoff (showcase)

A recipe browser with the same UI rendered twice — once by SvelteKit and once by React — against a shared Django + Wagtail backend and a FastAPI companion that handles portion scaling and nutrition lookups. Uses a shared drive for the Wagtail MEDIA_ROOT across web replicas so uploaded originals and auto-generated thumbnails are visible to every container.

  • Services: web (Django/Wagtail, 8000), fastapi (8001), svelte (SPA, 80), react (SPA, 80)
  • Storage: PostgreSQL, Redis, a media drive mounted on web
  • Edge cache: Enabled on svelte + react (long TTL on /_app/* + /assets/*)
  • Repo: gitlab.com/appmecca-sample-apps/recipe-cookoff

two-newsrooms (showcase)

A news / magazine site — Wagtail's canonical home turf. Editors publish articles through the Wagtail admin; two frontends (SvelteKit and React) render the same article stream identically. FastAPI exposes POST /summary/{id} — an extractive 3-bullet summariser cached per content hash.

  • Services: web (Django/Wagtail, 8000), fastapi (8000), svelte (SPA, 80), react (SPA, 80)
  • Storage: PostgreSQL, a media drive mounted on web (10 GB)
  • Edge cache: Enabled on svelte + react
  • Repo: gitlab.com/appmecca-sample-apps/two-newsrooms (being pushed)

photogallery (showcase)

A photographer's portfolio — the canonical edge-caching + images story on AppMecca. FastAPI's /img/{id}?w=N endpoint does CPU-bound Pillow resize on every cache miss and returns bytes with Cache-Control: public, max-age=31536000, immutable so the edge cache holds them indefinitely. Arbitrary widths are snapped to a seven-value lattice so the edge sees a bounded URL set per photo. Workers extract EXIF, detect the dominant colour for use as a layout placeholder while images load, and hourly prewarm preset widths for newly-added photos.

  • Services: web (Django/Wagtail, 8000), fastapi (8000), solid (SolidJS SPA, 80), worker, beat
  • Storage: PostgreSQL, Redis
  • Edge cache: Enabled on solid + long-TTL headers on every FastAPI resize response
  • Repo: gitlab.com/appmecca-sample-apps/photogallery

eventpass (showcase)

A conference / meetup ticketing app — the canonical story for why Beat earns its keep. Every minute, release_expired_holds flips expired reservations back to available; stop the Beat container and the demo visibly breaks (seats leak, events look sold out). FastAPI owns the transactional /hold and /confirm path under SELECT ... FOR UPDATE. Workers generate PDF tickets with embedded QR codes via reportlab + qrcode.

A URL shortener with a per-link analytics dashboard — the cleanest "why does each container exist" story of the five. FastAPI handles the sub-10 ms /r/{slug} redirect hot path (Django via WSGI would be overkill). Celery workers drain the click-event queue, enrich with user-agent + country, and persist to PostgreSQL. Beat rolls up hourly aggregates and seeds synthetic traffic. Wagtail owns the marketing shell. Two identical SPAs (SvelteKit + React) for framework A/B comparison.

  • Services: web (Django/Wagtail, 8000), fastapi (8000, /r/{slug}), svelte (SPA, 80), react (SPA, 80), worker, beat
  • Storage: PostgreSQL, Redis
  • Edge cache: Enabled on both svelte + react
  • Repo: gitlab.com/appmecca-sample-apps/shortlink

Platform-feature coverage

Every AppMecca capability is exercised by at least one of the seven apps. Use this table in reverse: pick a feature, find an app that demonstrates it, copy the pattern from its appmecca.yaml.

Feature Config key Demonstrated by
Single container, single service containers: [{name,dockerfile}] + one deploy[] hello-flask
Multi-service from ONE image multiple deploy[] entries sharing a container: django-celery-tasks, photogallery, eventpass, shortlink
Multi-container (separate images) multiple containers[] entries all 5 showcase apps
Managed PostgreSQL database database.enabled: true everything except hello-flask
Managed Redis cache cache.enabled: true everything except hello-flask + two-newsrooms
Shared drive across replicas storage.drives + deploy[].drives recipe-cookoff, two-newsrooms
Edge caching on a SPA deploy[].cache block all 5 showcase apps
SPA runtime config injection deploy[].type: spa + spa_root all 5 showcase apps
Inter-service URL templates ${service:name} all 5 showcase apps
Celery / portless workers deploy[].command: "celery …" (no port) django-celery-tasks, photogallery, eventpass, shortlink
Celery Beat (scheduled tasks) same, with celery -A … beat … photogallery, eventpass, shortlink
Per-service memory limits deploy[].resources.memory all 5 showcase apps
Per-service replicas deploy[].replicas recipe-cookoff, eventpass, shortlink, photogallery
Long-TTL Cache-Control on origin responses FastAPI returning custom headers photogallery (/img/{id}?w=N)
SELECT ... FOR UPDATE transactional path psycopg async pool in FastAPI eventpass (/hold, /confirm)
On-demand image resize Pillow in FastAPI photogallery
PDF generation with QR codes reportlab + qrcode in a worker eventpass
User-agent + geo enrichment Celery worker consuming Redis events shortlink
Multiple frontend frameworks SvelteKit, React, Vue 3, SolidJS across the five showcases

Validation status

These patterns are validated end-to-end on a live environment: a 2026-06-18 campaign deployed apps across 9 runtimes and confirmed database persistence (add a record → reload → it persists), Redis caching, drive storage + media (an uploaded file survives a reload), static sites + edge caching, workers + cron, and multi-branch deploys — plus multi-tenant isolation (you only ever see your own group's apps, logs, and backups). These checks now run in the platform's overnight test suite.

Deploying any sample app

Every sample app follows the same three-step workflow:

# 1. Register the app
mecca register git@gitlab.com:appmecca-sample-apps/<app-name>.git "<Title>" -e <env>

# 2. Build + deploy (auto-deploys on build success by default)
mecca build trigger -g git@gitlab.com:appmecca-sample-apps/<app-name>.git -e <env>

The mecca register step records the repo URL and config path, then runs a pre-flight check — AppMecca clones the repo, confirms the branch is reachable, and validates appmecca.yaml. It does not start a build. The mecca build trigger step hands the repo to the AppMecca build service, which builds the Docker images, pushes them to your private image registry, and then deploys them according to the app's appmecca.yaml.

For branch deployments, add -b <branch> to the build trigger:

mecca build trigger -g git@gitlab.com:appmecca-sample-apps/shortlink.git -b feature/dark-theme -e dev

Running locally

Every sample app ships with a Makefile. The larger showcases require PostgreSQL + Redis on the host, which you can bring up with Docker Compose if the app provides one, or install locally.

./apps.sh clone photogallery
cd photogallery
make install     # per-service deps
make dev-backend # in one terminal
make dev-worker  # in another
make dev-fastapi # in another
make dev-solid   # in another (port 5176)

See each app's own README for per-service local-dev instructions.

The full sample-app catalogue

The seven apps above are the AppMecca-authored full-stack showcases — the ones seeded from IDEAS.md that exercise the whole Django + Wagtail + Celery + FastAPI pipeline. Alongside them, the appmecca-sample-apps GitLab group contains ~40 additional smaller apps covering individual features and per-language patterns — hello-world servers in every major language, REST API + database apps across stacks, Redis/cache demos, workers, branch-deployment demos, and targeted feature showcases (auto-rollback-demo, bucket-demo, cron-demo, etc).

Every per-app .md file in this directory corresponds to a real repo under gitlab.com/appmecca-sample-apps. Run ./sample_apps/apps.sh clone-all to check them all out locally.