From a45f7dd4a4a6d2491e5e1edd3188a30f861cb5d1 Mon Sep 17 00:00:00 2001 From: Mauricio Siu <47042324+Siumauricio@users.noreply.github.com> Date: Sat, 24 May 2025 21:40:18 -0600 Subject: [PATCH] docs: enhance troubleshooting guide with new sections on Traefik network issues and Dokploy UI accessibility --- .../content/docs/core/troubleshooting.mdx | 279 ++++++++++++++++++ 1 file changed, 279 insertions(+) diff --git a/apps/docs/content/docs/core/troubleshooting.mdx b/apps/docs/content/docs/core/troubleshooting.mdx index 9299536..7c2d575 100644 --- a/apps/docs/content/docs/core/troubleshooting.mdx +++ b/apps/docs/content/docs/core/troubleshooting.mdx @@ -3,6 +3,8 @@ title: Troubleshooting description: Solve the most common problems that occur when using Dokploy. --- +import { Callout } from "fumadocs-ui/components/callout"; + ## Applications Domain Not Working? You see the deployment succeeded, and logs are running, but the domain isn't working? Here's what to check: @@ -166,6 +168,19 @@ volumes: - my-database:/var/lib/mysql ``` +### Use of closed network when restarting Traefik + +If you see this error in the logs of Traefik, it means that the network is being closed, this is the normal behavior when restarting Traefik. + +```bash +05/23/25, 12:21:12 PM info 2025-05-23T09:21:12Z ERR: error="accept tcp [::]:443: use of closed network connection" entryPointName=websecure +05/23/25, 12:21:12 PM info 2025-05-23T09:21:12Z ERR: error="accept tcp [::]:9000: use of closed network connection" entryPointName=traefik +05/23/25, 12:21:12 PM info 2025-05-23T09:21:12Z ERR: error="accept tcp [::]:80: use of closed network connection" entryPointName=web +05/23/25, 12:21:12 PM info 2025-05-23T09:21:12Z ERR: error="close tcp [::]:9000: use of closed network connection" entryPointName=traefik +05/23/25, 12:21:12 PM info 2025-05-23T09:21:12Z ERR: error="close tcp [::]:443: use of closed network connection" entryPointName=websecure +05/23/25, 12:21:12 PM info 2025-05-23T09:21:12Z ERR: error="close tcp [::]:80: use of closed network connection" entryPointName=web +``` + ### Creating Configuration Files If you need to create configuration files before deploying your compose setup: @@ -197,3 +212,267 @@ will need to use a public IP address. ```bash curl -sSL https://dokploy.com/install.sh | ADVERTISE_ADDR=your-ip sh ``` + + +## 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: + +```bash +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: +```bash +docker ps +``` + +You should see all four of these containers running: +```bash +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 +a29d56342175 redis:7 "docker-entrypoint.s…" 4 days ago Up 4 days 6379/tcp dokploy-redis.1.epl51a9bt8yr7ur0f1akeeyuk +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 +``` + +If all four 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: + +```bash +docker service logs dokploy # Dokploy UI +docker service logs dokploy-postgres # Postgres +docker service logs dokploy-redis # Redis +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`: + +```ts +> 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: +```bash +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: + +```shell +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: +```bash +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: + +```yaml +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: + +```yaml +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: +```bash +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: + + +Remove the dokploy-redis service: +```bash +docker service rm dokploy-redis + +# Create a new dokploy-redis service + docker service create \ + --name dokploy-redis \ + --constraint 'node.role==manager' \ + --network dokploy-network \ + --mount type=volume,source=redis-data-volume,target=/data \ + redis:7 +``` + +Remove the dokploy-postgres service: + +```bash +docker service rm dokploy-postgres + +# Create a new dokploy-postgres service + docker service create \ + --name dokploy-postgres \ + --constraint 'node.role==manager' \ + --network dokploy-network \ + --env POSTGRES_USER=dokploy \ + --env POSTGRES_DB=dokploy \ + --env POSTGRES_PASSWORD=amukds4wi9001583845717ad2 \ + --mount type=volume,source=dokploy-postgres-database,target=/var/lib/postgresql/data \ + postgres:16 +``` + + +Remove the dokploy-traefik service: + +```bash +docker service rm dokploy-traefik + +# Create a new dokploy-traefik service +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 \ + -p 80:80/tcp \ + -p 443:443/tcp \ + -p 443:443/udp \ + traefik:v3.1.2 +``` + +Remove the dokploy service: + +```bash +docker service rm dokploy + +# Create a new dokploy service + +# We need the advertise address to be set which is the Private IP of your server, you can get it by running the following command: + +# Run this command to get the private IP of your server: + +Copy this value and paste in the ADVERTISE_ADDR variable: +ip addr show | grep -E "inet (192\.168\.|10\.|172\.1[6-9]\.|172\.2[0-9]\.|172\.3[0-1]\.)" | head -n1 | awk '{print $2}' | cut -d/ -f1 + +# 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-docker-config,target=/root/.docker \ + --publish published=3000,target=3000,mode=host \ + --update-parallelism 1 \ + --update-order stop-first \ + --constraint 'node.role == manager' \ + -e ADVERTISE_ADDR="Eg: 192.168.1.100" \ + 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/ + + + +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/ +