Microweber + Dokploy: The 2-Minute Deploy Debugging Checklist

Microweber is a PHP-based site builder. Dokploy is a self-hosted PaaS that runs Docker workloads. The two together — Microweber deployed via Dokploy on a VPS — is a practical stack for self-hosters who want a CMS without subscribing to one. It's also one of the more common deploy-debugging conversations on subreddits like r/selfhosted.

The fixes follow a pattern. This is the 2-3 minute pre-deploy and post-failure checklist that catches the bulk of breakage.

The pre-deploy checklist

Run through these before you push the deploy button. Each takes seconds; together they catch ~80% of failures.

1. Confirm the database is reachable

docker compose exec dokploy-postgres pg_isready -U postgres
# or, if Postgres is host-installed:
sudo -u postgres psql -c '\l'

Microweber expects to connect to a database on first run. If the DB is unreachable, the install hangs without a useful error.

2. Check disk free

df -h /var
df -h /

Microweber's userfiles/ and Dokploy's image cache are both volume-backed. A 95%-full /var produces deploys that succeed silently and crash on first request when the volume hits 100%. Need at least 1GB free for a small Microweber install with reasonable headroom.

3. Pull image hash, not just :latest

In your docker-compose.yml for Microweber:

microweber:
  image: microweber/microweber:1.4.0   # not :latest

Pinning prevents the "it worked yesterday" problem when upstream pushes a breaking change. latest is a deploy-debugging accelerant.

4. Verify the reverse proxy port mapping

Dokploy fronts services with Traefik. Mismatched container/service ports cause silent 502s.

In Dokploy → Service → Network, confirm:

• Container port matches the port the app listens on inside the container (Microweber: 80).
• Domain is set, with SSL enabled if you're past initial install.

If you see "502 Bad Gateway" after a successful deploy, this is almost always the cause.

5. PHP memory and upload limits

Microweber defaults trip on real-world content uploads. Add these env vars to the service:

PHP_MEMORY_LIMIT=512M
PHP_POST_MAX_SIZE=64M
PHP_UPLOAD_MAX_FILESIZE=64M
PHP_MAX_EXECUTION_TIME=180

Without them, "deploy succeeded but admin login times out" is a common bug. PHP-FPM hits the default max_execution_time=30s on a slow first-load.

6. Persistent volumes mounted

In your service definition, confirm:

volumes:
  - microweber_userfiles:/var/www/html/userfiles
  - microweber_cache:/var/www/html/storage

Without these, a redeploy wipes uploaded media and rebuilt cache. Deploy 1 looks great. Deploy 2 looks empty. If your "site disappeared after I clicked redeploy" search led you here — this is almost certainly why.

When deploy fails — the diagnosis tree

"Service starts then exits"

docker logs <microweber-container> 2>&1 | tail -50

Two common patterns:

• Connection refused (database) → DB not ready when Microweber starts. Add a depends_on: condition: service_healthy clause and a healthcheck on the Postgres/MySQL service.
• Permission denied: /var/www/html/storage → Volume mounted but with wrong UID. Either chown the volume directory on the host, or set user: "33:33" (www-data) in the compose file.

"502 Bad Gateway"

Almost always Traefik can't reach the container.

docker compose exec dokploy-traefik wget -qO- http://microweber:80/

If this fails inside the proxy network, the container isn't on the proxy network. Add the network explicitly:

networks:
  - dokploy-network

networks:
  dokploy-network:
    external: true

"Login screen loads but admin times out"

PHP execution timeout. Set PHP_MAX_EXECUTION_TIME=180 in env, restart container.

If still timing out, check Postgres logs for slow queries. Microweber's first-time admin login runs migrations. On a small VPS with no swap, this can OOM.

"Site loads but no styles / 404 on /assets/"

Microweber writes asset URLs based on the install URL. If you installed at http://1.2.3.4 and now front it with https://example.com, the cached assets point to the IP.

Fix: clear storage/cache either via the admin UI or:

docker compose exec microweber rm -rf /var/www/html/storage/cache
docker compose restart microweber

"Deploy succeeds but a previous version still shows"

Browser cache, or Cloudflare cache if you're behind it.

# Bust Cloudflare cache for the site:
# Cloudflare dashboard → Caching → Purge Everything (or by URL)

Local browsers: Cmd+Shift+R / Ctrl+Shift+F5.

The 2-3 minute rollback

If a deploy goes wrong and you need to roll back fast:

# In Dokploy:
# Service → Deployments → click the previous deployment → "Redeploy"

Dokploy keeps the last N deployment images locally. If the previous deploy isn't visible, fall back to:

docker images | grep microweber
docker tag <previous-sha> microweber/microweber:rollback
# Update compose to use :rollback, redeploy.

Always test that you can roll back before you need to. Spinning up a deploy, then immediately rolling back to the previous, is a 5-minute drill that pays for itself the first time you need it for real.

Internal links

• Tutorial: Set up Traefik with SSL on a VPS
• Guide: Multiple Domains on One VPS
• Guide: VPS Backup Strategy
• ServerCompass: One-click Microweber + Dokploy templates