Skip to content

AppMecca Developer Guide

Welcome to the AppMecca developer documentation. This guide covers everything you need to deploy your applications on AppMecca.

What is AppMecca?

AppMecca is a deployment platform that runs your Docker containers. You give it a Git repository with a Dockerfile, and it handles building, deploying, routing, and monitoring your application.

You focus on your code. AppMecca handles the infrastructure.

Here's what it does for you:

  • Builds your Docker images automatically (via the AppMecca build service)
  • Stores images in the AppMecca private image registry
  • Deploys containers to AppMecca hosts
  • Routes HTTPS traffic to your app (via the AppMecca HTTPS router)
  • Checks your app is healthy and restarts it if needed
  • Provides managed PostgreSQL databases and Redis caches on demand

Prerequisites

Before you start, you need:

  1. A Git repository with your application code and a Dockerfile
  2. The mecca CLI installed on your machine (installation guide)
  3. An AppMecca environment set up by your administrator (e.g., dev, staging, prod)
  4. An account on that environment — sign up with mecca signup, then mecca login. Your administrator supplies the environment's API URL (mecca configure -e <env>).

Don't have an environment yet?

AppMecca environments are created by platform administrators using appmecca infra setup. If you don't have one, ask your infrastructure team to set one up for you.

How It Works (The Short Version)

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ Your Code │────>│  Build   │────>│  Deploy  │────>│   Live   │
│ + config  │     │ (docker) │     │ (hosts)  │     │ (HTTPS)  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
  1. You add an appmecca.yaml file to your repository (tells AppMecca what to build and how to run it)
  2. You run mecca register to register the app (this also runs a repository pre-flight check)
  3. You run mecca build trigger — it builds your image and deploys it automatically
  4. Your app is live at https://yourapp-web-yourgroup.dev.appmecca.net

That's it. Three commands to go from code to production.

Every service URL carries the service name

There is no bare yourapp.dev… hostname, even for a single-service app. A tenant URL is always {app}-{service}-{group}.{env}.appmecca.net, and a non-main branch adds its own segment: {app}-{branch}-{service}-{group}.{env}.appmecca.net.

New apps are private by default

A freshly registered app is reachable only to members of your group — anyone else gets an authentication challenge instead of your site. Run mecca app publish <app> when you're ready to make it public, or click Make public next to the Visibility badge on the app's overview in the dashboard.

I want to... Go to...
Deploy my first app right now Quick Start
Install the CLI Installing the CLI
Understand the config file Configuration Overview
Learn about builds How Builds Work
Deploy an app Deploying Your App
Deploy feature branches side by side Branch Deployments
Add a database Database Configuration
Add Redis caching Cache Configuration
See real examples Examples (39 sample apps)
Follow a step-by-step tutorial Tutorials (3 tracks, 8 parts each)
Add a custom domain Custom Domains
Fix a problem Troubleshooting

Tutorials

New to AppMecca? Follow a guided tutorial that takes you from hello-world to production in your language of choice. All three tracks build the same todo app with the same API, so frontends and backends are interchangeable.

Track Stack What You'll Build
Python + React Django + React + Celery Full-stack todo app with workers
Java + Vue Spring Boot + Vue 3 + Spring Task Full-stack todo app with workers
Node.js + Svelte Express + SvelteKit + BullMQ Full-stack todo app with workers

Each track has 8 parts covering: deployment, databases, multi-container builds, SPA config, background workers, branch deployments, internal service discovery, and production patterns.

Sample Apps

Seven sample applications exercise every part of the AppMecca platform end-to-end. Each one is a complete, working app you can clone and deploy. All sample apps are publicly available on GitLab.

App Scope What it shows
hello-flask minimal Simplest possible AppMecca app — one Flask container
django-celery-tasks workers Django + Celery from one image via command:
recipe-cookoff showcase Recipe browser with SvelteKit / React A/B comparison, drive-backed Wagtail media
two-newsrooms showcase Wagtail news site with FastAPI summariser, drive-backed media library
photogallery showcase Canonical edge-cache + on-demand Pillow resize story
eventpass showcase Conference ticketing where Beat is load-bearing (hold reaper)
shortlink showcase URL shortener with per-link analytics — sub-10 ms FastAPI redirect path

See the Sample Apps Reference for per-app service lists, appmecca.yaml snippets, and a feature-by-example cross-reference.