Dokploy

Dokploy Instance

Fix a Dokploy UI that isn't accessible and recreate the core Dokploy services.

My Dokploy UI Instance is Not Accessible

If you can't access your Dokploy UI instance, there could be several causes. While this issue won't occur with Dokploy Cloud (where our team manages the infrastructure), self-hosted instances might encounter configuration problems.

Let's go through the possible cases where your Dokploy UI instance might be inaccessible:

1. Insufficient Storage Space

If you've made many deployments and don't have available space on your server, the Dokploy database might enter recovery mode, preventing access to the user interface. Here's a quick solution to clear cache and free up server space:

docker system prune -a
docker builder prune -a
docker image prune -a

2. Container Race Condition During Restart

During a restart, a race condition might occur where Dokploy's dependent containers don't start in the correct order. To troubleshoot this:

First, verify the running containers:

docker ps

You should see all three of these containers running:

2a5b955c32b6   dokploy/dokploy:latest      "docker-entrypoint.s…"   4 days ago     Up 4 days     0.0.0.0:3000->3000/tcp, :::3000->3000/tcp                                                                             dokploy.1.4bkuszk98muz372kw5mvwkw0h
5a989bf52bc6   postgres:16                 "docker-entrypoint.s…"   4 days ago     Up 4 days     5432/tcp                                                                                                              dokploy-postgres.1.9hvjaxrmby7ex2denjtwo0csf
05be01c5612f   traefik:v2.5                "/entrypoint.sh trae…"   4 days ago     Up 4 days     0.0.0.0:80->80/tcp, :::80->80/tcp, 0.0.0.0:443->443/tcp, :::443->443/tcp, 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp   dokploy-traefik.1.2oktabjmfu558x2d2dy6czt8m

Note: If you're running a version older than v0.29.9, you'll also see a dokploy-redis container. Redis is no longer used in self-hosted Dokploy since v0.29.9.

If all three containers are running but you still can't access the interface, it's time to debug:

Debugging Process

1. Check Container Logs

Start by examining the logs of each container:

docker service logs dokploy # Dokploy UI
docker service logs dokploy-postgres # Postgres
docker logs dokploy-traefik # Traefik

2. Common Database Connection Issue

A common case is when the Postgres container starts after the Dokploy container, preventing Dokploy from connecting to the database. You might see logs like this when running docker service logs dokploy:

> dokploy@v0.22.3 start /app
> node -r dotenv/config dist/server.mjs

Default middlewares already exists
Network is already initilized
Main config already exists
Default traefik config already exists
Migration failed [Error: getaddrinfo ENOTFOUND dokploy-postgres] {
  errno: -3008,
  code: 'ENOTFOUND',
  syscall: 'getaddrinfo',
  hostname: 'dokploy-postgres'
}
Setting up cron jobs....
Main Server Error [Error: getaddrinfo ENOTFOUND dokploy-postgres] {
  errno: -3008,
  code: 'ENOTFOUND',
  syscall: 'getaddrinfo',
  hostname: 'dokploy-postgres'
}

To fix this, restart the Dokploy service:

docker service scale dokploy=0
# Then
docker service scale dokploy=1

3. Traefik Configuration Issues

If all containers are running but you still can't access the UI, and Dokploy logs show no errors, the Traefik container might have configuration issues.

When running docker logs dokploy-traefik, you might see errors like:

2025-04-07T15:20:18Z ERR Error occurred during watcher callback error="/etc/dokploy/traefik/dynamic/dokploy.yml: field not found, node: passHostHeader" providerName=file

First, try restarting Traefik:

docker restart dokploy-traefik

If you still can't access it and the same error persists in the Traefik logs, you'll need to check the Traefik configuration. In this case, the error indicates that the passHostHeader field is missing in the configuration.

If you've modified any Traefik configuration for an application and added invalid configuration, the logs will point to the error. For example, the error above mentions field not found, node: passHostHeader, which means we need to manually modify the configuration files in /etc/dokploy/traefik.

Here's an example of an invalid configuration:

http:
  routers:
    dokploy-router-app:
      rule: Host(`my-domain.com`)
      service: dokploy-service-app
      entryPoints:
        - web
      middlewares:
        - redirect-to-https
    dokploy-router-app-secure:
      rule: Host(`my-domain.com`)
      service: dokploy-service-app
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt
  services:
    dokploy-service-app:
      loadBalancer:
        servers:
          - url: http://dokploy:3000
          - passHostHeader: true

The correct configuration should be:

http:
  routers:
    dokploy-router-app:
      rule: Host(`my-domain.com`)
      service: dokploy-service-app
      entryPoints:
        - web
      middlewares:
        - redirect-to-https
    dokploy-router-app-secure:
      rule: Host(`my-domain.com`)
      service: dokploy-service-app
      entryPoints:
        - websecure
      tls:
        certResolver: letsencrypt
  services:
    dokploy-service-app:
      loadBalancer:
        servers:
          - url: http://dokploy:3000
        passHostHeader: true

After fixing the configuration, restart Traefik:

docker restart dokploy-traefik

You should now be able to access the user interface.

Recreate dokploy containers

In the case you want to recreate the dokploy services, you can do the following:

Important: Before recreating services, make sure you have backups of your data. Recreating services will not delete your volumes, but it's always good to have backups.

Recreate Postgres Service

Remove and recreate the dokploy-postgres service:

docker service rm dokploy-postgres

# Create a new dokploy-postgres service with Docker Secrets
docker service create \
  --name dokploy-postgres \
  --constraint 'node.role==manager' \
  --network dokploy-network \
  --env POSTGRES_USER=dokploy \
  --env POSTGRES_DB=dokploy \
  --secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \
  --env POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
  --mount type=volume,source=dokploy-postgres,target=/var/lib/postgresql/data \
  postgres:16

Note: Using Docker Secrets is the recommended approach for managing sensitive data like passwords. The secret is encrypted and only available to services that have been granted access to it.

Recreate Traefik Service

Remove the dokploy-traefik service:

# If you are using docker standalone traefik
docker rm -f dokploy-traefik

docker run -d \
    --name dokploy-traefik \
    --restart always \
    -v /etc/dokploy/traefik/traefik.yml:/etc/traefik/traefik.yml \
    -v /etc/dokploy/traefik/dynamic:/etc/dokploy/traefik/dynamic \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    -p 80:80/tcp \
    -p 443:443/tcp \
    -p 443:443/udp \
    traefik:v3.6.7

docker network connect dokploy-network dokploy-traefik

# If you are using docker service traefik
docker service rm dokploy-traefik

# Create a new dokploy-traefik service
docker service create \
  --name dokploy-traefik \
  --constraint 'node.role==manager' \
  --network dokploy-network \
  --mount type=bind,source=/etc/dokploy/traefik/traefik.yml,target=/etc/traefik/traefik.yml \
  --mount type=bind,source=/etc/dokploy/traefik/dynamic,target=/etc/dokploy/traefik/dynamic \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  --publish mode=host,published=443,target=443 \
  --publish mode=host,published=80,target=80 \
  --publish mode=host,published=443,target=443,protocol=udp \
  traefik:v3.6.7

Recreate Dokploy Service

Remove and recreate the dokploy service:

If the dokploy_auth_secret secret doesn't exist on your server (installations older than v0.29.3), create it first: openssl rand -hex 32 | docker secret create dokploy_auth_secret -

docker service rm dokploy

# Create the dokploy service
docker service create \
  --name dokploy \
  --replicas 1 \
  --network dokploy-network \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  --mount type=bind,source=/etc/dokploy,target=/etc/dokploy \
  --mount type=volume,source=dokploy,target=/root/.docker \
  --secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \
  --secret source=dokploy_auth_secret,target=/run/secrets/dokploy_auth_secret \
  --publish published=3000,target=3000,mode=host \
  --update-parallelism 1 \
  --update-order stop-first \
  --constraint 'node.role == manager' \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
  -e BETTER_AUTH_SECRET_FILE=/run/secrets/dokploy_auth_secret \
  dokploy/dokploy:latest

For Proxmox LXC environments, add the --endpoint-mode dnsrr flag to all services:

docker service create \
  --name dokploy \
  --replicas 1 \
  --network dokploy-network \
  --mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
  --mount type=bind,source=/etc/dokploy,target=/etc/dokploy \
  --mount type=volume,source=dokploy,target=/root/.docker \
  --secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \
  --secret source=dokploy_auth_secret,target=/run/secrets/dokploy_auth_secret \
  --publish published=3000,target=3000,mode=host \
  --update-parallelism 1 \
  --update-order stop-first \
  --constraint 'node.role == manager' \
  --endpoint-mode dnsrr \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
  -e BETTER_AUTH_SECRET_FILE=/run/secrets/dokploy_auth_secret \
  dokploy/dokploy:latest

Final Notes

While the specific issues may vary, the general troubleshooting approach remains similar to what we've described above, and is the general way we always follow when correcting a problem related to the dokploy instance not starting.. If you still can't access the user interface:

  1. Check that all containers are running properly
  2. Review the logs of each container for specific error messages
  3. Verify all configuration files
  4. Make sure to read the Traefik documentation for detailed configuration options: https://doc.traefik.io/traefik/

Dokploy Cloud

If you are using Dokploy Cloud, you don't need to worry about this, our team will handle the infrastructure for you.

Start using Dokploy Cloud https://app.dokploy.com/

Logs & Monitoring

Fix logs and monitoring that aren't loading on worker nodes or remote servers.

Cloudflare Tunnels

Learn how to use Cloudflare Tunnels to securely expose your Dokploy applications without opening ports on your server.

On this page

My Dokploy UI Instance is Not Accessible1. Insufficient Storage Space2. Container Race Condition During RestartDebugging Process1. Check Container Logs2. Common Database Connection Issue3. Traefik Configuration IssuesRecreate dokploy containersRecreate Postgres ServiceRecreate Traefik ServiceRecreate Dokploy ServiceFinal Notes