When you first install Dokploy, everything may look fine on localhost, but real problems start after the first public deployment. This Dokploy troubleshooting guide helps you fix SSL issues, reverse proxy problems, and failed deployments step-by-step, so your apps stay online and stable in production.

If you still need the base setup, you can follow this guide on how to install Dokploy on a Linux VPS.

How This Dokploy Troubleshooting Guide is Structured

This Dokploy troubleshooting guide focuses only on problems that appear after the platform is installed and your app is live on a public domain.

You will learn how to:

• Fix SSL certificates that do not issue or keep failing.
• Solve wrong domain routing and redirect loops.
• Debug reverse proxy and Traefik routing problems.
• Find and fix failed deployments and container health check errors.
• Fix apps that work locally but fail behind the proxy in Dokploy.

Basic Checks Before Deep Dokploy Troubleshooting

Before using this Dokploy troubleshooting guide for advanced issues, you must confirm these basic points first.

Check DNS and connectivity:

On your local machine or VPS, run the commands below:

dig yourdomain.com +short
dig app.yourdomain.com +short
nslookup yourdomain.com
ping -c 4 yourdomain.com

You should see the correct VPS IP in the output.

If you use a firewall like UFW on the VPS, use the commands below to check the status, and if ports 80 and 443 are not allowed, open the ports:

sudo ufw status
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Also, confirm that HTTP works:

curl -I http://yourdomain.com

You should get a 200 or 301 response, not timeouts.

SSL not Working in Dokploy

SSL problems are one of the most common reasons a new deployment fails right after going public. Typical symptoms include:

• The browser shows Connection not secure or Your connection is not private.
• Dokploy cannot create a Let’s Encrypt certificate for your domain.
• You only see the default Traefik certificate instead of your real domain cert.

To fix the issue, follow the steps below.

1. Make sure DNS points to the VPS:

dig yourdomain.com +short
dig app.yourdomain.com +short

If you use Cloudflare, set records to DNS only (grey cloud) while SSL is created.

2. Confirm HTTP challenge works. Let’s Encrypt needs port 80 open:

curl -v http://yourdomain.com
sudo ss -tulpn | grep ':80'

You should see a service listening on port 80 and a valid HTTP response.

3. Re-create or renew certificate in Dokploy: In the Dokploy UI, go to Domains/SSL, create or renew the certificate, and attach it to the correct app.

4. Validate SSL from the terminal:

curl -v https://yourdomain.com

Look for:

• * Connected to yourdomain.com.
• Certificate subject that matches your domain, not a default name.

If SSL still fails, this Dokploy troubleshooting guide recommends checking Traefik logs for ACME errors:

docker ps | grep traefik
docker logs -n 100 <traefik_container_name>

Wrong Domain Routing

Sometimes you get the wrong app on the right domain, or unbounded redirects between HTTP and HTTPS. Common symptoms include:

• Visiting https://app.yourdomain.com shows another service.
• Unbounded redirect loop between http:// and https://.
• The bare domain and the www domain fight each other.

1. Check where your domain actually goes. From your local machine, run the commands below:

curl -I http://app.yourdomain.com
curl -I https://app.yourdomain.com

Check Location: headers and status codes to see if there are loops or the wrong target.

2. Confirm only one service uses the domain: In Dokploy, make sure only one app or compose service is configured with app.yourdomain.com. If you use Docker Compose directly, you can check labels:

docker inspect <container_id> | jq '.[0].Config.Labels'

Look for traefik.http.routers.*.rule entries and confirm they match the domain you expect.

3. Avoid double redirects: If you force HTTPS in Dokploy and also in Cloudflare, you may create a loop. In the Cloudflare dashboard, set SSL/TLS mode to Full and disable extra Always Use HTTPS rules until the site works cleanly.

Reverse Proxy Issues

Reverse proxy issues in Dokploy usually involve Traefik not forwarding traffic correctly from the public domain to the internal container port.

• App is up in Dokploy, but times out in the browser.
• Only the default Traefik page appears on your domain.
• WebSockets or long-polling features fail, but simple pages work.

1. Test the app directly from the VPS:

SSH into the server and find your app container:

ssh root@your-vps-ip
docker ps

Then, run the command below and note the internal port, for example, 3000:

docker inspect <app_container_id> | jq '.[0].NetworkSettings.Ports'

Test it with:

curl -v http://127.0.0.1:3000

If this fails, the problem is inside the container or app.

2. Check Traefik is listening on 80 and 443:

sudo ss -tulpn | grep -E ':80|:443'
docker ps | grep traefik
docker logs -n 100 <traefik_container_name>

Look for bind errors, 502 errors, or routing problems.

3. Check Traefik labels for compose-based apps:

If you manage compose files, confirm labels use the dokploy-network and proper entrypoints:

traefik.http.routers.<name>.entrypoints=websecure
traefik.http.routers.<name>.tls.certresolver=letsencrypt
traefik.http.routers.<name>.rule=Host("app.yourdomain.com")

You can check labels with:

docker inspect <app_container_id> | jq '.[0].Config.Labels'

Failed Dokply Deployments

Sometimes a deployment looks successful in the UI, but the container exits, health checks fail, or the app never responds. Typical symptoms:

• Dokploy shows deployment finished, but the status is unhealthy.
• Container restarts in a loop.
• Logs show missing configuration or runtime errors.

1. View container logs:

On the VPS, run:

docker ps -a | grep <your-app-name>
docker logs -n 100 <app_container_id>

Look for build errors, migrations failing, or stack traces.

If you use the Dokploy API or CLI-style calls, you can fetch deployment logs like this, for example, from their API docs:

curl -X GET "https://your-dokploy-instance.com/api/deployment.logs?deploymentId=<DEPLOYMENT_ID>" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

2. Compare environment variables:

From inside the container run:

docker exec -it <app_container_id> env | sort

Compare this with your local .env file. Make sure keys like DATABASE_URL, REDIS_URL, JWT_SECRET, or API keys are set and correct.

3. Test database and dependencies:

From the app container run:

docker exec -it <app_container_id> sh
# inside container:
ping -c 4 db
nc -vz db 5432    # for PostgreSQL example
nc -vz redis 6379 # for Redis example

If these fail, update the Dokploy network or service configuration so containers can reach each other.

Dokploy Environment Variable Problems

Wrong or missing environment variables are a silent source of many bugs after deployment.

1. Dump production env:

From the app container run:

docker exec -it <app_container_id> printenv | sort

Check that:

• All required variables are present.
• URLs use your real domain.
• There are no leftover localhost values or wrong ports.

2. Check types and formats:

If your framework is strict with booleans or numbers, confirm values:

docker exec -it <app_container_id> sh -c 'echo "$NODE_ENV"; echo "$DEBUG"; echo "$PORT"'

Update them in Dokploy’s environment settings if needed, then redeploy.

Apps that Work Locally but Fail Behind Proxy

Many users report that their app runs perfectly on local localhost:3000, but breaks after the domain and SSL are added.

1. Search for hard-coded localhost:

On your dev machine, run:

grep -R "localhost" -n .
grep -R "127.0.0.1" -n .

Replace these with environment-based values or relative paths.

2. Check trusted proxy and headers:

Some frameworks, such as Express, Laravel, Django, Rails, etc., need proxy trust:

• For Express, in code: app.set('trust proxy', 1) when behind Traefik.
• For others, enable trusted proxies in the config so X-Forwarded-Proto and X-Forwarded-For are used.

Check headers from the browser:

curl -I https://app.yourdomain.com

Confirm X-Forwarded-Proto: https is present.

3. Fix CORS and cookies: If frontend and backend are separate, set allowed origin to your real domain and enable secure cookies when using HTTPS.

Where to Find Dokploy Logs and Validation Points

Logs and basic checks are your main tools for understanding what is really happening inside Dokploy and your containers.

On the VPS, you can use these useful commands:

# List all containers
docker ps -a

# Tail logs for a specific container
docker logs -f <container_id>

# Check CPU and memory use for all containers
docker stats

# Inspect a container in detail
docker inspect <container_id> | less

For system-level checks:

top           # or htop if installed
df -h         # check disk space
free -m       # check memory
journalctl -u docker --no-pager | tail -n 50

Use these to confirm each change from this Dokploy troubleshooting guide really fixes the issue before moving on.

When to Consider a Better Linux VPS for Dokploy

If this Dokploy troubleshooting guide helps you fix the configuration, but your apps still crash under real traffic, your problem may be limited resources, not just settings.

Clear signs to move to a better VPS:

• Frequent OOM (out-of-memory) kills in logs.
• High CPU load for long periods.
• Slow response times or timeouts during simple requests.

Check basic resource usage:

top
free -m
df -h
docker stats

If numbers stay high even on light traffic, moving your Dokploy stack or critical services to a strong Linux VPS can make your reverse proxy and deployments much more stable.

If you keep changing domains or need better DNS management for SSL and routing, you can also manage domains from PerLod.

Conclusion

Post-install issues in Dokploy usually come from DNS, SSL, reverse proxy routing, or bad configuration inside containers, not from the platform itself. This Dokploy troubleshooting guide gives you clear checks to debug SSL errors, routing mistakes, failed deployments, and local-vs-production differences so your apps stay stable in real-world traffic.

If stability problems continue even after fixes, consider upgrading to a more powerful Linux VPS and reviewing your app architecture for better resource usage.

We hope you enjoy this Dokploy troubleshooting guide. For more detailed platform-specific issues and updates, you can also check the official Dokploy documentation.

FAQs