Skip to content

Branch Demo API

A Node.js/Express REST API demonstrating AppMecca branch deployments. Deploy the main branch and feature branches side-by-side, each with its own URL and database.

Overview
Tech Stack Node.js / Express
Services 1 (api)
Database Yes (PostgreSQL)
Branches main, feature/dark-theme, feature/pagination
Pattern Branch deployments

Branches

Branch What It Adds
main Basic CRUD API for items
feature/dark-theme Adds theme field to items, new /api/themes endpoint, database migration
feature/pagination Adds ?page=N&limit=N query params to the list endpoint with total/page metadata

The appmecca.yaml

containers:
  - name: branch-demo-api
    dockerfile: Dockerfile
    context: .

deploy:
  - name: api
    container: branch-demo-api
    port: 3000
    health_check:
      path: /health

database:
  enabled: true

The configuration is identical across all branches -- the API code and database schema are what change between branches. AppMecca handles creating separate infrastructure for each branch deployment.

Key Concepts

Branch Deployments

When you deploy a branch, AppMecca creates a completely isolated environment:

  • Separate URL: the sanitised branch name is inserted into the hostname
  • Separate database: each branch gets its own PostgreSQL database, so main's data is never visible to a feature branch
  • Separate drives and buckets: storage is per-branch too
  • Independent lifecycle: deploy, undeploy, and update branches independently

The hostname is built as {app}-{service}-{group} for the production branch, and {app}-{branch}-{service}-{group} for any other branch — note the branch segment sits before the service name:

Branch Hostname
main branch-demo-api-api-{group}.dev.appmecca.net
feature/pagination branch-demo-api-feature-pagination-api-{group}.dev.appmecca.net

Replace {group} with your group slug — or just run mecca app show branch-demo-api -e dev, which prints the exact URLs.

Step-by-Step Deployment

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

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

mecca app deploy -e dev branch-demo-api

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

mecca app deploy -e dev branch-demo-api -b feature/pagination

Both deployments run simultaneously:

  • main at https://branch-demo-api-api-{group}.dev.appmecca.net
  • feature/pagination at https://branch-demo-api-feature-pagination-api-{group}.dev.appmecca.net

Comparing Branches

The health endpoint on each branch returns its version and branch name:

# Main branch
curl https://branch-demo-api-api-{group}.dev.appmecca.net/health
# {"status":"healthy","version":"1.0.0","branch":"main"}

# Feature branch
curl https://branch-demo-api-feature-pagination-api-{group}.dev.appmecca.net/health
# {"status":"healthy","version":"1.2.0","branch":"feature/pagination"}

Environment variables are per-branch too

mecca var set applies to every branch of the app unless you narrow it with -b. If a feature branch needs a different value, set it explicitly: mecca var set branch-demo-api FEATURE_FLAG=on -b feature/pagination -e dev. Variable changes take effect on the next deploy, not immediately.

What's Next