Skip to content

How Deployment Works

AppMecca uses a pull-based deployment model. When you run a deploy command, AppMecca does not SSH into your servers or push code directly. Instead, it writes a deployment request to a queue, and agents running on each AppMecca host pick it up and act on it.

This design is reliable and scalable -- agents independently pull work, and if one host is temporarily unavailable, it catches up when it comes back online.

The Deployment Flow

Here is what happens when you run mecca app deploy:

You (CLI)                    PostgreSQL deploy queue       Host agents
    |                             |                             |
    |  1. Queue deployment        |                             |
    |---------------------------->|                             |
    |                             |  2. Agent polls (every 5s)  |
    |                             |<----------------------------|
    |                             |                             |
    |                             |  3. Leader claims request   |
    |                             |<----------------------------|
    |                             |                             |
    |                             |  4. Leader sets up routing  |
    |                             |         (router rules, DNS) |
    |                             |                             |
    |                             |  5. All agents deploy       |
    |                             |         containers          |
    |                             |                             |
    |                             |  6. Health checks pass      |
    |                             |                             |
    |                             |  7. Status: COMPLETED       |
    |                             |<----------------------------|

Step by Step

  1. You run mecca app deploy myapp -e dev on your laptop
  2. The CLI verifies your app is registered and a container image exists in the image registry
  3. The CLI writes a QUEUED row to the PostgreSQL deploy queue
  4. Agents on the hosts poll the PostgreSQL deploy queue every 5 seconds and find the queued deployment
  5. One agent claims leadership via an atomic database update (first one wins)
  6. The leader creates the routing: a routing group, HTTPS router rules, and DNS records
  7. All agents pull the Docker image from the image registry and start the container
  8. The health check confirms the app is responding on the configured path
  9. The deployment status is updated to COMPLETED

Your app is now live and receiving traffic.

Deployment Statuses

Status Meaning
QUEUED Request written to the deploy queue, waiting for an agent to pick it up
IN_PROGRESS An agent has claimed the deployment and is working on it
READY_TO_DEPLOY Leader finished infrastructure setup, all agents deploying containers
COMPLETED All containers running and healthy, traffic is flowing
FAILED Something went wrong (check mecca queue status <id> or mecca queue logs <id> for details)

First Deploy vs Redeploy

The first time you deploy an app, AppMecca does extra work:

First Deploy Redeploy
Create routing group Yes No (reuses existing)
Create router rules Yes No (reuses existing)
Create DNS record Yes No (reuses existing)
Allocate host ports Yes No (reuses existing)
Pull Docker image Yes Yes (new image)
Start container Yes Yes (replaces old)
Health check Yes Yes

On a redeploy, the old container is stopped and replaced with the new one. The routing infrastructure stays in place, so the URL does not change and traffic switches over as soon as the new container passes its health check.

Domain Routing

AppMecca automatically assigns an HTTPS URL to every service that declares a port. The pattern is:

https://{app}-{service}-{group}.{env}.{domain}

So an app called myapp in group yourgroup, with frontend and backend services, gets:

https://myapp-frontend-yourgroup.dev.yourdomain.io
https://myapp-backend-yourgroup.dev.yourdomain.io

The service name is always in the URL

There is no bare myapp.dev.… URL — not even for a single-service app. A one-service app called myapp whose service is named web is reachable at myapp-web-yourgroup.dev.yourdomain.io. Run mecca app show myapp to see the real URLs AppMecca assigned.

Branch deployments insert the sanitised branch name before the service:

https://myapp-feature-payments-frontend-yourgroup.dev.yourdomain.io

The main branch is the exception — it carries no branch segment. See Branch Deployments for the full URL patterns.

Background workers do not get URLs

Services defined without a port in appmecca.yaml (like Celery workers or cron jobs) run as containers but do not get a public URL. Only services with a port receive router routing.

Leader Election

When multiple hosts are running, AppMecca uses leader election to avoid duplicate routing setup:

  • Leader: The first agent to claim the deployment. It creates the routing group, router rules, and DNS records, then deploys the container.
  • Followers: All other agents. They wait for the leader to finish the routing setup, then deploy the container on their host.

This happens automatically. You do not need to configure or think about it.

Multi-host deployments

Set replicas on a service (1-3) to run it on more than one host. The platform router distributes traffic across the replicas, and each replica is placed on a different host — so if one host goes down, traffic continues flowing to the others.

Next Steps