Skip to content

Deploying Your App

This page walks you through deploying an application to AppMecca. Before you deploy, you need a registered app with at least one successful build.

Prerequisites

Before running mecca app deploy, make sure:

  1. Your app is registered -- run mecca app list -e dev to check
  2. A build exists -- run mecca build list -a myapp -e dev to verify
  3. Repository preflight passed -- a newly registered app stays quarantined until its repo is proven buildable; mecca app show myapp -e dev reports the verdict

No build yet?

If you have not built your app, deploy will fail with an "Image not found" error. Build first:

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

See Triggering a Build for details.

Command Flags

mecca app deploy TARGET [options]

TARGET is a positional argument — either a registered app name, or a Git URL (which registers and deploys the app in one step).

Flag Short Description
--env -e Target environment (resolved from mecca.conf default when omitted)
--branch -b Branch to deploy (default: main)
--image-tag Deploy a specific image tag instead of building
--no-build Deploy the latest existing image — skip the build
--no-deploy Build only, no auto-deploy
--config-path Path to appmecca.yaml in the repo (default: repo root)
--skip-preflight Bypass the repository preflight gate

Two flags are Python-CLI only

--force (deploy even if the app already exists, Git-URL targets) and --skip-check (skip the git ls-remote accessibility pre-check) exist on pipx run appmecca and not on the mecca you installed from npm or Homebrew — see FEATURES #366. They are named here rather than dropped, so the capability is not lost from the record.

There is no --services or --replicas flag

mecca app deploy deploys all of the app's services and uses the replicas value declared per service in appmecca.yaml. Replica counts are a config decision, not a deploy-time one — change deploy[].replicas (1-3) and redeploy. See Services.

Deploy the Latest Build

mecca app deploy myapp -e dev
Expected output 
Deploying myapp to dev...
  Found 2 container(s): frontend, backend
  frontend: appmecca/dev/myapp/frontend:latest
  backend: appmecca/dev/myapp/backend:latest
  Deployment name validation passed
Deployment deploy-a1b2c3d4-e5f6-7890-abcd-ef1234567890 queued successfully
  Status: queued

The CLI verifies that container images exist in the image registry, then queues the deployment. Host agents pick it up within seconds.

Deploying a branch

By default, this deploys the main branch. To deploy a different branch, add -b:

mecca app deploy myapp -e dev -b feature/payments

Each branch gets its own isolated containers, database, ports, and URL. See Branch Deployments for the full guide.

Deploy a Specific Version

Every build is tagged with the Git commit hash. You can deploy a specific version instead of latest:

mecca app deploy myapp -e dev --image-tag abc1234

This is useful when you want to deploy an older build, or when multiple builds exist and you want to be explicit about which one to use.

Finding available tags

Run mecca build list -a myapp -e dev. The Tag column is what you pass to --image-tag, and Status tells you which tags are usable — only a succeeded build has an image in the registry.

build list shows build history, not what is serving traffic; read the live tag from mecca app show myapp -e dev.

Restarting a Single Service

mecca app deploy always deploys every service in the app — there is no per-service deploy flag. If only one service needs to be bounced (and the image has not changed), restart it instead:

mecca app restart myapp web -e dev

This leaves the other services untouched. See Service Management.

Build and Deploy in One Command

mecca build trigger already does both — a deploy is queued automatically and runs the moment the build succeeds:

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

It is the fastest way to go from code changes to a running deployment. Pass --no-deploy if you want the build only. There is no --deploy flag.

Expected output 
Build queued: 2d0ad0c2-563b-4f66-898a-49bde612bf16
Deploy queued: f82c2671-5157-4df0-a0ba-29cf0b584267 (runs automatically when build succeeds)
  Build status:  mecca queue status 2d0ad0c2-563b-4f66-898a-49bde612bf16
  Deploy status: mecca queue status f82c2671-5157-4df0-a0ba-29cf0b584267

For an app that is already registered, mecca app redeploy myapp does the same thing from the stored repo URL — no -g needed.

Service Placement

When you deploy, AppMecca automatically decides which hosts run which services. The placement engine is memory-aware and tiered: the first few hosts form a base tier spread across separate availability zones and are spread-packed (each new service lands on the emptiest host), and any scale-out hosts beyond that are bin-packed (filled one at a time) so they stay cold until the base is full. Every container has a hard memory limit, and placement keeps a safety-margin of headroom on each host for the brief blue/green overlap during a redeploy. Replicas of the same service are always placed on different hosts (a hard anti-affinity constraint) for high availability.

Replica counts are set per service in appmecca.yaml (deploy[].replicas, 1-3 — see Services). There is no deploy-time override; change the config and redeploy.

After a deployment completes, mecca queue status <id> shows the placement plan -- which services were assigned to which hosts.

What Happens During a First Deploy

The very first deployment of an app involves extra setup. Here is the full sequence:

  1. Port allocation -- AppMecca assigns host ports (from the 7001-8999 range) to each service
  2. Routing group creation -- A routing group is created for each service with a port
  3. Router rules -- Rules are added to the platform HTTPS router to route traffic by hostname
  4. DNS registration -- A wildcard DNS record points *.dev.yourdomain.io at the router
  5. Container deployment -- The Docker image is pulled and the container is started
  6. Health check -- The router confirms the container is responding on the configured health check path
  7. Traffic flows -- HTTPS requests to your app URL reach the container

After the first deploy, steps 1-4 are skipped on subsequent deploys. Only the container is replaced.

What Happens During a Redeploy

Redeploys are zero-downtime. AppMecca runs the old and new containers side by side (blue/green) and only cuts traffic over once the new one is proven healthy:

  1. The new image is pulled from the image registry
  2. A new container starts on a temporary port, alongside the still-serving old one
  3. The new container is health-checked; once it passes, the router switches traffic to it
  4. The old container is drained and removed after in-flight requests finish

The routing (routing group, router rules, DNS) remains unchanged, so the URL does not change.

A failed redeploy costs you nothing

If the new container never passes its health check, the old one keeps serving and the new one is discarded. A broken deploy does not take your app down.

Using Environment Defaults

To stop retyping -e on every command, set a default environment once:

mecca configure -e dev

mecca then resolves the environment from (in order) an explicit -e flag, the APPMECCA_ENV environment variable, and finally the [default] section of ~/.appmecca/mecca.conf.

export APPMECCA_ENV=dev     # per-shell override
mecca app deploy myapp      # no -e needed

There is no APPMECCA_BRANCH, and APPMECCA_APP does not fill in the app name here

mecca app deploy takes its target as a required positional argument — it is not defaulted from APPMECCA_APP, so mecca app deploy on its own is an error. And no APPMECCA_BRANCH variable exists: -b defaults to main and must be passed explicitly for any other branch.

APPMECCA_APP is honoured by the commands that take -a/--app as a filter flag — mecca logs, mecca build list, mecca queue list.

Troubleshooting Deploy Issues

"App not found"

Your app is not registered. Register it first:

mecca register git@github.com:yourorg/myapp.git -e dev

"Image not found"

No build exists for this app, or the tag you specified does not exist. Check what is available, then trigger a build if needed:

mecca build list -a myapp -e dev
mecca build trigger -e dev -g git@github.com:yourorg/myapp.git

Deployment stays in QUEUED status

Check whether the action is being held back by an admission gate, which explains the hold in plain language:

mecca queue diagnose <action-id> -e dev

If it reports no blockers and the action still never starts, the host agents may be down — that is a platform-side problem, so contact your administrator. See Troubleshooting.

Next Steps