Skip to content

Undeploying

Undeploying removes a running application from your environment. It stops the containers, removes the platform router's routing, and deregisters DNS records. Registry data (builds, config, images) is preserved by default so you can redeploy later.

Command Flags

mecca app undeploy APP_NAME [options]

APP_NAME is a required positional argument.

Flag Short Description
--env -e Target environment (resolved from APPMECCA_ENV or the mecca.conf default when omitted)
--branch -b Branch to undeploy (omit to resolve the app's live branch)
--purge Also delete registry data (config, build and env-var records)
--force Skip confirmation prompt

-b resolves automatically for a single-branch app

Omit -b and AppMecca resolves whichever branch is actually running — so a dev-only app undeploys cleanly without you naming the branch. If the app is running on multiple branches, -b becomes required.

Basic Undeploy

mecca app undeploy myapp -e dev

To undeploy a specific branch instead of main:

mecca app undeploy myapp -e dev -b feature/payments
Expected output 
Undeploy 'myapp' from dev? [y/N]: y
Undeploying myapp from dev...
Undeploy queued: deploy-a1b2c3d4-e5f6-7890-abcd-ef1234567890
  Registry data preserved for redeployment

AppMecca asks for confirmation before proceeding. Type y to confirm.

Undeploy is not instant

Like deployment, undeploy is pull-based. The CLI queues the request and agents execute it. It typically completes within 10-15 seconds.

What Gets Cleaned Up

When you undeploy an app, the following resources are removed:

Resource Cleaned Up
Running containers Stopped and removed on every host
Router rules Deleted (traffic stops routing to the app)
Routing groups Deleted
DNS records Deregistered
Port allocations Released (ports become available for other apps)
Deploy record Cleared from the registry
Config, build and env-var records Preserved (use --purge to delete)

After undeploy completes, the app's URL will stop working, but your build history and configuration are preserved for redeployment.

Images and data are not deleted

Undeploy does not delete your Docker images, your database, or your drive contents. They remain available for future deployments. To fully purge an app, use mecca app delete instead.

Redeploying After Undeploy

Since registry data is preserved by default, you can redeploy with a simple:

mecca app deploy myapp -e dev

No need to re-register the app or trigger a new build.

Purge All Data

If you want to also delete all registry data (CONFIG, BUILD, ENV records), use --purge:

mecca app undeploy myapp -e dev --purge
Expected output 
Undeploy 'myapp' from dev? --purge will delete all registry data. [y/N]: y
Undeploying myapp from dev...
Undeploy queued: deploy-a1b2c3d4-e5f6-7890-abcd-ef1234567890
  All registry data will be removed

With --purge, the following are also deleted:

  • Registration record -- your app's registration and resolved appmecca.yaml configuration
  • Build records -- history of all builds and their image tags
  • Environment variables -- values set via mecca var set

After a purge, you would need to re-register the app and trigger a new build before deploying again.

When to use --purge

Use --purge when you are permanently removing an app and don't plan to redeploy it. For temporary removal (maintenance, cost savings, etc.), omit --purge so you can easily redeploy later.

Skip Confirmation

To skip the confirmation prompt (useful in scripts or CI/CD pipelines):

mecca app undeploy myapp -e dev --force

You can combine flags:

mecca app undeploy myapp -e dev --force --purge

Undeploy vs Unregister vs Apps Delete

These commands serve different purposes:

Command What It Does
mecca app undeploy Stops the running deployment. Registry data preserved by default. Images and data remain.
mecca app undeploy --purge Stops deployment and deletes registry data. Images and data remain.
mecca app unregister Alias for app delete — a permanent purge. Not a registry-only removal.
mecca app delete Full purge. Removes everything: images, build projects, secrets, logs, the database, and registry data.

Use undeploy when you want to stop running the app but might redeploy it later — it stops the containers and leaves everything else intact. Use app delete when you want to completely remove all traces of the app from the environment. ⚠ app unregister is not a lighter middle option: it is an alias for app delete and destroys just as much.

Apps Unregister

⚠ unregister is an alias for app delete — a permanent purge. It is not a registry-only removal: the database is backed up and dropped, and images, build history, secrets and every platform resource belonging to the app are destroyed. To stop an app without destroying anything, use undeploy above.

mecca app unregister myapp -e dev

Add --force to skip the confirmation prompt. After unregistering, you can re-register with mecca register.

Apps Delete

Fully purge an app and all its resources:

mecca app delete myapp -e dev

This removes the app's image repositories, build project, secrets, collected logs, object-storage data, its database (backed up first, then dropped), and all registry records. Add --force to skip confirmation and auto-undeploy if the app is currently running.

app delete drops your database

The tenant database is backed up and then dropped. Backup bundles taken with mecca app backup survive, so take one first if the data matters.

Branch cleanup

To fully clean up a feature branch (including its database, backups, and registry records), use mecca app delete myapp -e dev -b feature/payments. See Branch Deployments for details.

How Undeploy Works Internally

The undeploy process follows the same pull-based model as deployment:

  1. You run mecca app undeploy myapp -e dev on your laptop
  2. The CLI writes an UNDEPLOY_REQUESTED row to the PostgreSQL deploy queue
  3. The leader agent picks it up and executes the cleanup:
    • Stops containers on its host
    • Deletes the router rules and routing groups
    • Deregisters the DNS records
    • Clears deploy state from the registry (config, build and env-var records preserved unless --purge)
  4. Follower agents stop their containers
  5. The status is updated to UNDEPLOYED

Fault-tolerant cleanup

If any single cleanup step fails (for example, a routing group was already deleted), the undeploy continues with the remaining steps. Errors are logged but do not halt the process.

Verifying Undeploy Completed

After undeploying, check the app's state:

mecca app show myapp -e dev

The app should no longer report running. To watch the undeploy action itself, pass the action ID that mecca app undeploy printed:

mecca queue status <action-id> -e dev

You can also check that the URL is no longer accessible — take the exact hostname from mecca app show, since it includes the service name and your group slug:

curl -s -o /dev/null -w "%{http_code}" https://myapp-web-yourgroup.dev.yourdomain.io
# Should return 503 or connection refused

Next Steps