mirror of
https://github.com/Dokploy/website
synced 2025-06-26 18:16:01 +00:00
docs: enhance troubleshooting guide with new sections on Traefik network issues and Dokploy UI accessibility
This commit is contained in:
Mauricio Siu
@@ -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/
|
||||
|
||||
|
||||
<Callout title="Dokploy Cloud" type="info">
|
||||
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/
|
||||
</Callout>
|
||||
|
||||
Reference in New Issue
Block a user