Operations & Troubleshooting

Practical diagnosis, log inspection, lock release, and recovery procedures for epd.

---

1. Deployment Fails on Health Probe

Symptom:

✖ Health check failed on 203.0.113.10: replica did not become healthy within 60s.
Rolling back to live slot...

Explanation:

The new version was booted in the idle slot, but requests to healthcheck.path (default: /) did not return an HTTP status in 200-399 before timing out.

Diagnostic Steps:

1. Inspect container crash logs:

   epd logs --service web --lines 100

2. Verify application startup speed: If your app takes 45 seconds to compile assets or connect to a database on cold start, increase the timeout in epd.yml:

   healthcheck:
     path: /health
     timeout: 90
     delay: 5

3. Verify port binding: Ensure your app listens on the port configured under servers.<service>.port (e.g. 3000), and binds to 0.0.0.0 (not 127.0.0.1 inside Docker).

---

2. Deployment Lock is Held

Symptom:

✖ Another deployment is currently in progress (lock held by deployer-laptop at 14:22).

Explanation:

epd takes a lock on every server before deploying: a directory at <remote_root>/apps/<app>/lock (/var/lib/epd/apps/<app>/lock by default), created with mkdir, which is atomic. It holds who took it, the machine and process ID, the time, and what the deploy was doing. On Ctrl-C or SIGTERM, epd releases the locks it holds, including one it was in the middle of taking, but only where the lock still records this deploy as its holder. That release waits up to about 25 seconds for slow servers. A second Ctrl-C exits at once, which can leave the lock; epd lock release clears it. If your computer lost its connection, or the deploy was killed with kill -9 mid-deployment, the lock stays until someone releases it.

epd lock status flags a lock as probably stale when its process is no longer running on the same machine, or when it has been held for more than 6 hours.

Solution:

# Check lock details and whether it looks stale:
epd lock status

# Clear the lock once you have confirmed no deploy is running:
epd lock release

Only release a lock you are sure is stale. Releasing a live deploy's lock lets a second deploy run at the same time.

---

3. Investigating the Shared Traefik Proxy

If domains are not resolving or returning 404 page not found:

Check Proxy Status:

epd proxy status

View Live Traefik Logs:

epd proxy logs -f

Inspect Generated Dynamic Routing YAML:

epd proxy routes

Verify that your domains, ports, and entrypoints match what you declared in epd.yml.

Reboot Traefik:

If Traefik needs a restart:

epd proxy reboot

---

4. Disaster Recovery & Emergency Rollback

To immediately revert to the previously working build:

epd rollback

To list all past deployments saved on the server:

epd rollback --list

And roll back to a specific tagged release:

epd rollback <version>

---

Next Steps

• Explore the CLI Commands Reference
• Review the Complete epd.yml Schema
• Read the GitHub Actions CI/CD Guide