Skip to content

Part 1: Your First Deployment

Deploy a hello-world Django application to AppMecca in under 10 minutes.

What you'll learn

  • Installing and authenticating the AppMecca CLI
  • Writing a minimal Django application with a health endpoint
  • Creating a Dockerfile and appmecca.yaml configuration
  • Registering, building, deploying, and undeploying an application
  • Viewing build and deployment logs

What you'll need

  • An AppMecca environment already provisioned (ask your platform team)
  • Python 3.11+ installed locally
  • Docker installed locally (for testing your image)
  • A GitHub account with a repository for your app
  • npm install -g appmecca (or brew install appmecca), or access to the mecca binary

Step 1: Install and authenticate the CLI

Install the AppMecca CLI and log in with your GitHub account:

npm install -g appmecca

appmecca git-auth login --provider github

This opens a browser window for GitHub's device authorization flow. After approving, verify your credentials:

appmecca git-auth status

Set default environment

Avoid typing -e dev on every command by exporting defaults:

export APPMECCA_ENV=dev
export APPMECCA_APP=todo-app

Explicit flags always override these environment variables.

Step 2: Create the Django application

Start a new project and add a minimal view:

mkdir todo-app && cd todo-app
pip install django
django-admin startproject config .
python manage.py startapp core

Edit core/views.py:

from django.http import JsonResponse


def health(request):
    return JsonResponse({"status": "healthy"})


def index(request):
    return JsonResponse({"message": "Hello from AppMecca!"})

Edit config/urls.py:

from django.urls import path
from core.views import health, index

urlpatterns = [
    path("health", health),
    path("", index),
]

Add "core" to INSTALLED_APPS in config/settings.py and set ALLOWED_HOSTS = ["*"].

Create requirements.txt:

django==5.1
gunicorn==23.0

Step 3: Write the Dockerfile

FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
RUN python manage.py collectstatic --noinput 2>/dev/null || true

EXPOSE 8000
CMD ["gunicorn", "config.wsgi:application", "--bind", "0.0.0.0:8000"]

Test it locally:

docker build -t todo-app .
docker run -p 8000:8000 todo-app
# Visit http://localhost:8000/health

Step 4: Write appmecca.yaml

Create appmecca.yaml in the repository root:

containers:
  - name: todo-app
    dockerfile: Dockerfile
    context: .

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

Commit and push everything to your GitHub repository.

Unknown keys are silently ignored

appmecca.yaml ignores any key it does not recognise — no error, no warning. A typo like helth_check: or contaners: simply disappears, and you discover it as a missing behaviour at deploy time. Copy key names exactly.

Step 5: Register and build

Register the application with AppMecca:

mecca register git@github.com:yourorg/todo-app.git -e dev
mecca app list -e dev
mecca app show todo-app -e dev

Register runs a pre-flight check, not a build

mecca register clones your repository and validates that AppMecca can reach it, that appmecca.yaml exists and parses, and that the Dockerfiles it names are present. It does not queue a build. Until the pre-flight passes, builds and deploys are refused — re-run it with mecca app recheck todo-app -e dev after fixing anything it reports.

Trigger a build. This queues a build action and returns immediately; a deploy is queued automatically after a successful build:

mecca build trigger -e dev -g git@github.com:yourorg/todo-app.git

The command prints the build's action ID. Follow it with:

mecca build status -e dev BUILD_ID
mecca build logs -e dev BUILD_ID

Use --no-deploy if you want to build without deploying:

mecca build trigger -e dev -g git@github.com:yourorg/todo-app.git --no-deploy

List builds for your app:

mecca build list -e dev --app todo-app

Step 6: Deploy

Deploy the latest build:

mecca app deploy todo-app -e dev

Monitor the deployment. mecca queue status takes the action ID printed by the deploy command (a prefix of 8 characters or more is enough):

mecca queue status ACTION_ID -e dev
mecca queue status ACTION_ID -e dev --json
mecca queue list -a todo-app -e dev      # every in-flight action for this app

Once the status shows completed, your app is live:

mecca app show todo-app -e dev

The URL always includes the service name — https://todo-app-web-yourgroup.dev.yourdomain.com for the web service above. There is no bare todo-app.dev... hostname, even though this app has only one service.

Step 7: Clean up

When you are done experimenting, undeploy and unregister:

mecca app undeploy todo-app -e dev
mecca app undeploy todo-app -e dev --force   # skip confirmation
mecca app unregister todo-app -e dev

Unregister is a permanent purge

⚠ app unregister delegates to app delete — a permanent purge, not a registry-only removal. It backs up and then drops the database, and deletes the built images from the image registry along with build history, stored secrets, and every platform resource the app owns. To stop an app without destroying anything, use mecca app undeploy instead.

What's next

Your app returns static JSON. In Part 2: Adding a Database, you will add PostgreSQL, Django models, and a REST API for managing todos.