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 uses an atomic lock file (/var/lib/epd/locks/<app>.lock) to prevent concurrent deployments from colliding. If your computer lost internet connection or was killed with kill -9 mid-deployment, the lock might remain active.

Solution:

# Check lock details:
epd lock status

# Forcefully clear the lock:
epd lock release

---

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