Services & Logs¶

Once your application is deployed, AppMecca provides commands to check on your running services, view logs, restart containers, and stop or start individual services.

Listing Running Services¶

To see every app in your environment:

mecca app list -e dev

Expected output

App                       Tag          Services                  Deployed
------------------------------------------------------------------------------------------
myapp                     abc1234      frontend, backend         2026-01-15T10:30:45
another-app               xyz9876      web                       2026-01-14T12:00:00

For one app's detail — its services, their URLs, visibility, and deploy status:

mecca app show myapp -e dev

For a branch deployment, add -b:

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

Command reference¶

Flag	Short	Description
`--env`	`-e`	Environment name (may be omitted once you have set a default with `mecca configure`)
`--branch`	`-b`	Git branch. Omit to resolve the branch the app is running on (falling back to your production branch)
`--json`		Output as JSON (a global flag, available on every command)

APP_NAME is a required positional argument on mecca app show.

Quick check after deploying

Run mecca app show myapp -e dev right after mecca app deploy to confirm all services started successfully, and to read the real URL for each one. If a service shows as unhealthy, check the logs.

What a service's status means¶

Each service tile on the dashboard shows one of four statuses. Every host reports its running containers every 30 seconds, and the status comes from those reports.

Status	What it means
Running	At least one host with an up-to-date report is running this service.
Not running	Every host was heard from, and none is running this service. This is what you see after you stop a service.
Status unknown	The platform cannot tell. The tile gives the reason.
Edge-served	A static site. The CDN serves it, so there is no container to run.

AppMecca shows Not running only when it has heard from every host. If one host did not report, it says Status unknown instead. That host could still be running the service.

Status unknown shows one of these reasons:

Reason	What it means
couldn't read the host inventories	The platform could not read the hosts' reports. Try again shortly.
no host is reporting	No host is checking in. A paused environment looks like this.
this app's name is registered by more than one group	Two groups registered the same name, so the reports cannot be told apart.
a host runs an older agent	A host's agent is too old to say whether its report is current.
a host's container list is stale	A host could not reach Docker, so its report may be out of date.
a host stopped reporting	A host went quiet but is not yet out of the pool. It may still be running the service.

A stale list or a quiet host usually clears within a few minutes. A name registered by two groups lasts until one of them renames the app, and an older agent lasts until the platform updates it.

The running count on a tile (declared 2 · running 2) counts hosts, not containers. During a deploy, the old and new containers share a host for a short time, and that host counts once. If some hosts report from an outdated container list, the tile shows a caption such as 1 verified · 1 unverified.

The Services running card counts only services that run containers. Static services are left out.

To see the raw value, run mecca app show myapp -e dev --json. Each service has a status and a runtime object. The Services section of the API reference documents every field.

Viewing Logs¶

AppMecca collects your containers' stdout and stderr automatically. You can read them from your own machine — there is no server to log into.

There is one command, mecca logs, and --type selects what you see:

Invocation	Shows
`mecca logs <app> --type container -s <service>`	Container output only — what your process printed.
`mecca logs <app>`	Everything — container output plus build, deploy and platform logs.

View recent container logs¶

mecca logs myapp --type container -s web -e dev

This shows the most recent output from the web service. Replace web with the name of any service defined in your appmecca.yaml; omit -s to see every service.

Expected output

2026-01-15 10:23:01 [INFO] Starting gunicorn 21.2.0
2026-01-15 10:23:01 [INFO] Listening at: http://0.0.0.0:8000
2026-01-15 10:23:01 [INFO] Using worker: sync
2026-01-15 10:23:02 [INFO] Booting worker with pid: 12
2026-01-15 10:23:15 [INFO] GET /health 200 0.002s
2026-01-15 10:23:45 [INFO] GET / 200 0.015s

Widening or narrowing the window¶

Both commands default to the last hour. Use --since to change it, and -n/--limit to cap the number of lines (default 100, max 1000):

mecca logs myapp --type container -s web -e dev --since 24h
mecca logs myapp --type container -s web -e dev --since 7d -n 500
mecca logs myapp --type container -s web -e dev --level error
mecca logs myapp --type container -s web -e dev --search "timeout"

There is no per-replica filter

Container logs for a service are interleaved across its replicas. (Do not confuse this with mecca deploy logs --replica, which is a different command and does exist.)

There is no follow / tail mode

mecca logs has no -f / --follow flag — each invocation returns a snapshot. To watch a deploy in progress, re-run the command, or follow the deploy itself with mecca queue status <action-id>.

Logs for a specific deployment or build¶

Use mecca logs (the unified command) with an ID:

mecca logs --deployment 50553200 -e dev
mecca logs myapp --type deploy -e dev
mecca logs myapp --type build -e dev

Log retention

Container logs are collected by the platform and retained for the lifetime of the environment. When an operator tears the environment down, its logs are removed with it.

Restarting a Service¶

To restart a service (stops the container and starts a fresh one with the same image):

mecca app restart myapp web -e dev

The service name is an optional second positional argument. Omit it to restart every service on the app:

mecca app restart myapp -e dev

The restart is queued, not performed inline — the command returns as soon as the actions are accepted:

Expected output

Restart myapp/web? [y/N]: y
Restart queued: web (1 action)

  Status:  mecca app show myapp

To skip the confirmation prompt, add --force:

mecca app restart myapp web -e dev --force

Command reference¶

Flag	Short	Description
`--env`	`-e`	Environment name (may be omitted once you have set a default)
`--branch`	`-b`	Git branch. Omit to resolve the branch the app is running on (falling back to your production branch)
`--force`		Skip confirmation (`--json` implies it)

APP_NAME is a required positional argument; the service name is an optional second positional.

It queues — it does not wait

There is no --wait or --timeout flag. Follow progress with mecca app show myapp or mecca queue list -a myapp.

A function service cannot be restarted

A service that runs as a function (runtime: function) has no container, so restart, stop and start are refused for it. On an app that also has container services, the app-wide form skips the function and acts on the rest. Deploy the app to publish a change. See Function Services.

Common reasons to restart a service:

Your app is in a bad state (memory leak, stuck process)
You changed environment variables with mecca var set and need the app to pick them up
A downstream dependency (database, external API) recovered and you want the app to reconnect

Restart vs. redeploy

mecca app restart restarts the container with the same image. It does not build new code or change the deployment. To ship new code, use mecca app deploy myapp (which builds and deploys) or mecca build trigger followed by mecca app deploy.

Stopping a Service¶

To stop a service without removing the deployment:

mecca app stop myapp worker -e dev --force

Omit the service name to stop every service on the app.

Expected output

Stop queued: worker (1 action)

  Start:   mecca app start myapp
  Status:  mecca app show myapp

Stopping a service halts its containers on every host. The app stays registered and deployed.

A stopped container is removed within the hour

Each host cleans up stopped containers once an hour. Until that happens, mecca app start brings the service back. After it, there is no container left to start, so the start is refused. Deploy to bring the service back:

mecca app deploy myapp --no-build -e dev

Stop flags¶

Flag	Short	Description
`--env`	`-e`	Environment name (may be omitted once you have set a default)
`--branch`	`-b`	Git branch. Omit to resolve the branch the app is running on (falling back to your production branch)
`--force`		Skip confirmation (`--json` implies it)

APP_NAME is a required positional argument; the service name is an optional second positional.

Starting a Service¶

To start a previously stopped service:

mecca app start myapp worker -e dev

Expected output

Start queued: worker (1 action)

  Status:  mecca app show myapp

The start command does not confirm (unlike stop and restart).

If the host has already removed the stopped container, the start is refused. mecca queue status <action-id> shows "no container for … on any host — a stopped container is pruned hourly; redeploy", and on the dashboard the tile reads Not running · Start failed — the container may have been removed; Deploy to bring it back. The dashboard toasts "start queued" first, then the outcome once the platform has one.

Start flags¶

Flag	Short	Description
`--env`	`-e`	Environment name (may be omitted once you have set a default)
`--branch`	`-b`	Git branch. Omit to resolve the branch the app is running on (falling back to your production branch)

APP_NAME is a required positional argument; the service name is an optional second positional. Like restart and stop, start queues the work and returns — there is no --wait or --timeout.

Scaling a Service¶

A service runs on one host by default. To run it on more — up to three, each on a different host, so a host failure does not take the service down:

mecca app scale myapp web 3 -e dev

Expected output

✓ Scale queued: web → 3 (a1b2c3d4)

  Watch it: mecca queue status a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d -e dev

The count is remembered, so it survives later deploys. Setting it to the value it already has does nothing at all — no write, no deploy — so nudging a number back to where it started never costs you a restart.

Add --wait to block until the redeploy finishes. It reports the declared count read back from the platform, not the number you typed: changing the setting and applying it are two separate things, and only reading it back shows that both happened.

mecca app scale myapp web 3 --wait -e dev

Expected output

✓ web now declares 3 replica(s).

If the deploy fails, the command says so and exits non-zero — it never reports the service as scaled when it is not.

Some services cannot be scaled¶

A service declared singleton: true in appmecca.yaml runs on exactly one host by design — a scheduler that fires jobs, for instance, would fire each one twice if a second copy ran. Scaling one is refused, and the message names the remedy: remove the flag from appmecca.yaml if the service is in fact safe to run more than once.

Static sites are refused too. They are served from a CDN rather than from a container, so there is no container to make copies of.

One scale at a time¶

While a deploy is already running for that app and branch, a scale is refused rather than queued behind it. The refusal names the action that is in the way, so you can watch that one finish and then scale:

✗ 'myapp' (main) already has a DEPLOY in flight — wait for it to finish, then scale.

  Watch it: mecca queue status 4f9c1e77-2b3a-4c5d-9e8f-1a2b3c4d5e6f

This is deliberate. Two overlapping changes to the same app's shape would race, and the loser's count would be silently discarded.

The same applies to the app's configuration: if a config save or another scale lands between the moment your command reads the app and the moment it writes, your change is refused rather than applied over theirs. Re-run it and it will go through.

Scaling redeploys what is RUNNING¶

The redeploy a scale queues does not build anything — it re-deploys the image your service is already running. That matters if you have rolled back: a rollback puts an older image back without building, so the newest image your app has built is not the one it is serving. Scaling ships the one it is serving, so it cannot quietly undo a rollback.

It also means a service with nothing running cannot be scaled. If the app has never deployed, or you have undeployed it, the scale is refused and asks you to deploy it first:

mecca app deploy myapp -e dev

If the count saved but the deploy did not¶

Very occasionally the count is saved and the redeploy cannot be queued. The command says so explicitly, rather than reporting a plain failure — because the change is saved, and re-running the same scale would then correctly report that there is nothing to do. Apply it with:

mecca app redeploy myapp -e dev

The same wording appears if you scale to a count the service already declares while a previous scale is still un-deployed: the message reports both numbers — what is declared and what is running — so the two are never confused.

Scale flags¶

Flag	Short	Description
`--env`	`-e`	Environment name (may be omitted once you have set a default)
`--branch`	`-b`	Git branch. Omit to resolve the branch the app is running on (falling back to your production branch)
`--wait`		Block until the redeploy finishes, then report the declared count

APP_NAME, the service name and the count are all required positional arguments. The count must be 1, 2 or 3; anything else is refused before any request is sent.

Checking Multiple Services¶

For multi-service applications (e.g., a web server and a background worker), check each service individually:

# Every service, its URL and health
mecca app show myapp -e dev

# Container output, per service
mecca logs myapp --type container -s web -e dev
mecca logs myapp --type container -s worker -e dev

Common Patterns¶

Debugging a failing health check¶

If mecca app show reports a service as unhealthy:

Check the logs for error messages:

mecca logs myapp --type container -s web -e dev

Look for startup errors (missing environment variables, database connection failures, port conflicts).

Verify your health check path matches what your app actually serves:

# In appmecca.yaml:
health_check:
  path: /health
# Your app must answer GET /health with a 200.

Give the app enough time to boot. health_check.startup_timeout defaults to 120 seconds (range 30–600); a slow-starting runtime that needs longer will be marked failed before it is ready.

Health check thresholds have a minimum of 2

healthy_threshold and unhealthy_threshold both accept 2–10. Writing 1 is rejected outright — it is not silently accepted.

Investigating a crash loop¶

If a container keeps restarting:

Read the logs to catch the error:

mecca logs myapp --type container -s web -e dev --level error

Look for patterns: does it crash immediately on startup, or after running for a while? A crash within seconds of every start, with no application error logged, usually means the container ran out of memory.
Check the memory limit. resources.memory requires a unit suffix:

resources:
  memory: 512m     # correct — 512 megabytes

A bare number is interpreted as bytes, and 512mb is not a recognised value at all. Use k, m, or g.

!!! note "resources.cpu does nothing" The schema accepts resources.cpu, but no part of the platform applies it. Only resources.memory has an effect.

Check whether the issue is environment-specific (works locally but fails on AppMecca) by reviewing the environment variables:
```
mecca var list myapp -e dev
```

Remember that mecca var set changes take effect on the next deploy — setting a variable does not restart anything by itself.

Next Steps¶

Database Operations -- Backup, restore, and manage your database
Domain Routing -- Understand how URLs map to your services
Troubleshooting -- Solutions to common problems