Skip to content

How Builds Work

Before AppMecca can deploy your application, it needs to turn your source code into a Docker image. This page explains what happens during a build and why it works the way it does.

The Build Pipeline

When you trigger a build, AppMecca runs a fully managed pipeline:

Your Git repo → AppMecca build service (clone + docker build) → private image registry
  1. Clone — The AppMecca build service clones your Git repository
  2. Read config — The build service reads your appmecca.yaml to find out which containers to build
  3. Build — Docker builds each container image using the Dockerfile you specified
  4. Push — The finished images are pushed to the AppMecca private image registry

After the build completes, the images are ready to deploy.

You never manage build servers

The build service is fully managed. AppMecca creates and configures the build project for you. There are no build servers to maintain, patch, or scale.

Where Images Are Stored

Every container you define in appmecca.yaml gets its own repository in the AppMecca private image registry. The naming pattern is:

appmecca/{environment}/{app}/{container-name}

For example, if your environment is dev, your app is myapp, and your appmecca.yaml defines a container called web:

appmecca/dev/myapp/web

For a multi-container app with frontend and backend containers:

appmecca/dev/myapp/frontend
appmecca/dev/myapp/backend

Image repositories are created automatically when you trigger your first build. You never need to create them manually.

Image Tagging

Every image AppMecca builds gets two tags:

Tag Example Purpose
Git commit hash a1b2c3d Identifies exactly which code was used
latest latest Always points to the most recent build

The commit hash tag is the important one. It gives you full traceability: if something goes wrong in production, you can look at the running image tag and know exactly which commit it came from.

appmecca/dev/myapp/web:a1b2c3d    ← this specific commit
appmecca/dev/myapp/web:latest     ← always the newest build

When you deploy, AppMecca uses the commit hash tag by default, not latest. This ensures deployments are deterministic and reproducible.

Every Build Is Fresh

AppMecca does not use Docker layer caching between builds. Every build starts from scratch.

This is a deliberate design choice:

  • Reproducibility — The same commit always produces the same image, regardless of what was built before
  • No stale layers — You never get an old cached dependency when you expected a fresh install
  • Simpler debugging — If a build fails, you know it's your code or Dockerfile, not a caching issue

Optimize your Dockerfile instead

Since builds are always fresh, write your Dockerfile so the expensive steps (like npm install or pip install) come before the frequently-changing steps (like COPY . .). Docker's build-time layer caching within a single build still works. Only cross-build caching is disabled.

# Good — dependencies are installed before code is copied
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci                    # Only re-runs if package.json changes
COPY . .                      # Changes frequently
RUN npm run build

Build Duration

Build times depend on your Dockerfile and dependencies. Some typical ranges:

App type Typical build time
Simple Python/Flask 1-3 minutes
Node.js with npm install 2-5 minutes
Multi-stage build with compilation 3-8 minutes
Large monorepo (multiple containers) 5-15 minutes

Since all builds are fresh, the first build and subsequent builds take roughly the same time. If your builds feel slow, focus on optimizing your Dockerfile (smaller base images, fewer layers, multi-stage builds).

What Triggers a Build

Builds are triggered manually. AppMecca does not watch your repository for changes or build automatically on push. You decide when to build by running:

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

You can build any branch by adding -b:

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

This gives you full control over what gets built and when. See Triggering a Build for all the options.

No automatic builds (yet)

If you want CI/CD-style automatic builds on every push, you can add the mecca build trigger command to your CI pipeline (GitHub Actions, GitLab CI, etc.).

Build vs Deploy

Building and deploying are separate steps in AppMecca:

Step What it does Command
Build Creates a Docker image from your code mecca build trigger
Deploy Runs the image on AppMecca hosts mecca app deploy

This separation means you can:

  • Build once, deploy many times (to different environments)
  • Build without deploying (to test that your Dockerfile works)
  • Roll back to a previous build without rebuilding

Build and deploy together is the default

A plain mecca build trigger already queues both a build and a deploy that runs the moment the build succeeds (and is skipped if the build fails):

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

Pass --no-deploy to opt out and build only. There is no --deploy flag — deploy-on-success is already the default.

Repository Preflight

When you register an app, AppMecca runs an automatic preflight on the repository before anything can build or deploy. It clones the repo and checks four things:

  1. The credential can reach the repo and the branch
  2. There is an appmecca.yaml
  3. The effective config is valid
  4. The Dockerfiles the config references exist

Until preflight passes, the app is quarantined — every build, deploy, and retry is refused with the preflight verdict, and the dashboard shows only the verdict plus Re-check / Delete. This catches a bad repo URL, a missing or broken config, or a missing Dockerfile in seconds, instead of after a full build round-trip.

The verdict is one of:

Verdict Meaning
ready The repo is buildable — build and deploy are unlocked
no_access The credential can't reach the repo or branch
needs_config No appmecca.yaml was found
config_invalid The config is present but invalid

After you fix the problem — registering the environment's deploy key on the repo, or authoring/fixing the config — re-run the check:

mecca app recheck myapp
mecca app recheck myapp -b feature

It converges on a fresh verdict (about 30 seconds). When it reports ready, build and deploy unlock.

Escape hatch: --skip-preflight

mecca app deploy myapp --skip-preflight bypasses the gate — an escape hatch for a false negative (say, a transient Git-provider blip). Prefer mecca app recheck first, since it re-runs the real check.

Private Repositories

If your Git repository is private, AppMecca needs a credential to clone it — either your OAuth login or a per-environment SSH deploy key held in the platform secret store. You set this up once per environment with the appmecca git-auth commands. See Triggering a Build for the setup steps.

Supported Git hosts

AppMecca clones from github.com, gitlab.com and bitbucket.org. Self-hosted Git servers are not supported.

Next Steps