Part 1: Your First Deployment

Deploy a hello-world Express app to AppMecca in under ten minutes.

Mix and match

If you've completed another tutorial track, you can mix and match -- any frontend from one track works with any backend from another. The API contract is the same across all tracks.

What you'll learn

• Writing a minimal Express app with a health endpoint
• Creating a Dockerfile for Node.js
• Writing an appmecca.yaml build/deploy manifest
• Authenticating, registering, building, deploying, and undeploying an app

What you'll need

• An AppMecca environment already set up (appmecca infra setup -e dev completed)
• Node.js 20+ installed locally (for development)
• A Git repository (GitHub or GitLab) for your app code

Set default environment

Avoid typing -e dev on every command:

export APPMECCA_ENV=dev

Or store it persistently in your CLI config:

mecca configure -e dev

The app name is a positional argument

Most mecca app … commands take the app name as a positional argument — mecca app deploy todo-app, mecca app show todo-app. There is no environment variable that fills it in for you, so the examples below always name the app explicitly.

Write the Express app

Create a new directory and initialise the project:

mkdir todo-app && cd todo-app
npm init -y
npm install express

Create index.js:

const express = require("express");
const app = express();
const PORT = process.env.PORT || 3000;

app.get("/health", (_req, res) => {
  res.json({ status: "healthy" });
});

app.get("/", (_req, res) => {
  res.json({ message: "Hello from AppMecca!" });
});

app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
});

Create the Dockerfile

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "index.js"]

Add a .dockerignore:

node_modules
.git

Write appmecca.yaml

This file tells AppMecca how to build and deploy your app:

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

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

Unknown keys are silently ignored

appmecca.yaml discards any key it does not recognise — no error, no warning. Misspell health_check as healthcheck and it simply vanishes; you discover it as a missing behaviour at deploy time. Copy key names exactly.

Authenticate with your Git provider

AppMecca needs read access to clone your repository during builds:

appmecca git-auth login --provider github

This opens a browser for the OAuth Device Authorization flow. Follow the prompts to authorize AppMecca.

Check auth status

Run appmecca git-auth status at any time to verify your tokens and SSH key status.

Commit, push, and register

Commit your code and push to your Git remote, then register the app:

git init && git add -A && git commit -m "initial commit"
git remote add origin git@github.com:yourorg/todo-app.git
git push -u origin main

mecca register git@github.com:yourorg/todo-app.git

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 after fixing whatever it reports.

Trigger a build

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

The command queues the build and returns immediately, printing an action ID; a deploy is queued automatically once the build succeeds. Pass --no-deploy to build only:

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

Check on it:

mecca build status <build-id>
mecca build logs <build-id>
mecca build list

Deploy

mecca app deploy todo-app

Watch the deployment progress. mecca queue status takes the action ID the deploy printed (an 8-character prefix is enough):

mecca queue status <action-id>
mecca queue status <action-id> --json
mecca queue list -a todo-app        # everything in flight for this app

Once the status shows completed, your app is live.

Find the URL

mecca app show todo-app

The URL always includes the service name: https://todo-app-web-yourgroup.dev.yourdomain.com. There is no bare todo-app.dev… hostname, even with a single service.

Clean up

When you are done, undeploy the app. This stops the containers but keeps the registry entry, build history and database:

mecca app undeploy todo-app

To skip the confirmation prompt:

mecca app undeploy todo-app --force

To fully remove the app:

mecca app unregister todo-app

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 AppMecca's image registry along with build history, stored secrets and every platform resource the app owns. Use mecca app undeploy to stop an app without destroying anything (covered in Part 8).

What's next

In Part 2: Adding a Database, you will add PostgreSQL with Knex.js migrations and learn the database management commands.