Skip to content

Branch Demo Fullstack

A Flask API + React SPA demonstrating AppMecca branch deployments with a multi-container full-stack application. Deploy the main branch and feature branches side-by-side, each with its own frontend, backend, and database.

Overview
Tech Stack Flask + React / Vite / nginx
Services 2 (backend, frontend)
Database Yes (PostgreSQL)
Branches main, feature/tags
Pattern Branch deployments, multi-container, SPA runtime config

Branches

Branch What It Adds
main Notes app with title and content fields
feature/tags Adds tags to notes, tag filter UI, new database migration, /api/tags endpoint

The appmecca.yaml

containers:
  - name: backend
    dockerfile: backend/Dockerfile
    context: backend/

  - name: frontend
    dockerfile: frontend/Dockerfile
    context: frontend/

deploy:
  - name: backend
    container: backend
    port: 5000
    path: /api
    health_check:
      path: /api/health

  - name: frontend
    container: frontend
    type: spa
    command: 'nginx -g "daemon off;"'   # serves the built bundle from a container
    spa_root: /usr/share/nginx/html
    port: 80
    health_check:
      path: /health
    environment:
      PUBLIC_API_URL: "${service:backend}"

database:
  enabled: true

This is the same configuration on both branches. The type: spa setting enables runtime config injection so PUBLIC_API_URL is resolved at deploy time, not build time. Each branch deployment gets a different backend URL automatically.

type: spa must be unambiguous

A type: spa service needs either a command: (it runs in a container, as here) or a static_site: block (it is built and served from the edge, with no container). Declaring type: spa with neither is a hard validation error — the platform cannot tell which of the two you want. This app uses the container form, which is why command: is present.

Key Concepts

Branch Deployments with Multi-Container Apps

When deploying a branch of a multi-container app, AppMecca creates isolated infrastructure for every service:

  • Separate URL per service, per branch — the sanitised branch name is inserted before the service name (lowercased, with every character other than a letter, digit or hyphen turned into a hyphen: release/1.0.0 → release-1-0-0)
  • Separate database: each branch gets its own PostgreSQL database
  • Automatic wiring: ${service:backend} resolves to the correct branch-specific backend URL
Branch Service Hostname
main frontend branch-demo-fullstack-frontend-{group}.dev.appmecca.net
main backend branch-demo-fullstack-backend-{group}.dev.appmecca.net
feature/tags frontend branch-demo-fullstack-feature-tags-frontend-{group}.dev.appmecca.net
feature/tags backend branch-demo-fullstack-feature-tags-backend-{group}.dev.appmecca.net

Replace {group} with your group slug, or run mecca app show branch-demo-fullstack -e dev to see the exact URLs.

SPA Runtime Config and Branch Isolation

The type: spa configuration ensures the frontend always talks to its own branch's backend:

  1. On main: PUBLIC_API_URL resolves to the main backend URL
  2. On feature/tags: PUBLIC_API_URL resolves to the feature branch backend URL

The frontend reads this at runtime via window.__APPMECCA_CONFIG__, so no rebuild is needed when URLs change.

Step-by-Step Deployment

# 1. Register and deploy main
mecca register git@gitlab.com:appmecca-sample-apps/branch-demo-fullstack.git \
  -e dev

mecca build trigger \
  -e dev \
  -g git@gitlab.com:appmecca-sample-apps/branch-demo-fullstack.git

mecca app deploy -e dev branch-demo-fullstack

# 2. Deploy feature branch side-by-side
mecca build trigger \
  -e dev \
  -g git@gitlab.com:appmecca-sample-apps/branch-demo-fullstack.git \
  -b feature/tags

mecca app deploy -e dev branch-demo-fullstack -b feature/tags

Comparing Branches

  • Main frontend: https://branch-demo-fullstack-frontend-{group}.dev.appmecca.net -- notes with title + content
  • Feature frontend: https://branch-demo-fullstack-feature-tags-frontend-{group}.dev.appmecca.net -- notes with tags, tag filter bar

What's Next