From 17e1ae05d31ad38f2be03642e04999b50a1e837b Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Tue, 7 Jul 2026 10:14:50 -0600 Subject: [PATCH] docs: document full service setup for existing Docker Swarm and drop vestigial ADVERTISE_ADDR env The Existing Docker Swarm section only created the network and the dokploy service, so installs failed against current versions that require the dokploy_postgres_password and dokploy_auth_secret Docker secrets, the dokploy-postgres service, and Traefik (issue #111). It now mirrors what install.sh does today, minus the swarm re-initialization. Also remove the ADVERTISE_ADDR env passed to the dokploy service in install.sh and the docs: the app stopped reading process.env.ADVERTISE_ADDR in February 2025, and the private-IP lookup step in troubleshooting only existed to fill it. The recreate-service commands now also mount the auth secret so recreated instances don't fall back to the insecure hardcoded default, and the advertise-addr customization section documents the ADVERTISE_ADDR env override instead of a script line that no longer exists. --- .../content/docs/core/manual-installation.mdx | 70 ++++++++++++++++--- .../content/docs/core/troubleshooting.mdx | 20 +++--- apps/website/public/install.sh | 1 - 3 files changed, 69 insertions(+), 22 deletions(-) diff --git a/apps/docs/content/docs/core/manual-installation.mdx b/apps/docs/content/docs/core/manual-installation.mdx index 20f12b0..ba8028b 100644 --- a/apps/docs/content/docs/core/manual-installation.mdx +++ b/apps/docs/content/docs/core/manual-installation.mdx @@ -165,7 +165,6 @@ install_dokploy() { --update-parallelism 1 \ --update-order stop-first \ --constraint 'node.role == manager' \ - -e ADVERTISE_ADDR=$advertise_addr \ -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ dokploy/dokploy:latest @@ -250,10 +249,13 @@ This structured format clearly lays out the prerequisites, steps, and post-insta The --advertise-addr parameter in the docker swarm init command specifies the IP address or interface that the Docker Swarm manager node should advertise to other nodes in the Swarm. This address is used by other nodes to communicate with the manager. -By default, this script uses the external IP address of the server, obtained using the `curl -s ifconfig.me` command. However, you might need to customize this address based on your network configuration, especially if your server has multiple network interfaces or if you're setting up Swarm in a private network. +By default, the script auto-detects the server IP address (the installer at `dokploy.com/install.sh` prefers a private RFC1918 address and falls back to the public IP). However, you might need to customize this address based on your network configuration, especially if your server has multiple network interfaces or if you're setting up Swarm in a private network. -To customize the --advertise-addr parameter, replace the line: `advertise_addr=$(curl -s ifconfig.me)` with your desired IP address or interface, for example: -`advertise_addr="192.168.1.100"` +To customize it, set the `ADVERTISE_ADDR` environment variable when running the script: + +```bash +curl -sSL https://dokploy.com/install.sh | sudo ADVERTISE_ADDR=192.168.1.100 sh +``` :warning: This IP address should be accessible to all nodes that will join the Swarm. @@ -275,33 +277,83 @@ docker service create \ **Note:** The `--endpoint-mode dnsrr` flag is required for Docker services to work properly in Proxmox LXC containers due to networking limitations. -## Existing Docker swarm +## Existing Docker Swarm -If you already have a Docker swarm running on your server and you want to use dokploy, you can use the following command to join it: +If you already have a Docker Swarm running on your server, do **not** use the installation script — it forces the node to leave the current swarm (`docker swarm leave --force`) and re-initializes it, which would disrupt your existing services. +Instead, run the following steps on a **manager** node. They replicate exactly what the install script does, minus the swarm initialization: ```bash +# 1. Create the network docker network create --driver overlay --attachable dokploy-network +# 2. Create the config directory mkdir -p /etc/dokploy +chmod 777 /etc/dokploy -chmod -R 777 /etc/dokploy +# 3. Create the secrets (Postgres password + auth secret) +openssl rand -base64 32 | tr -d "=+/" | cut -c1-32 | docker secret create dokploy_postgres_password - +openssl rand -hex 32 | docker secret create dokploy_auth_secret - -docker pull dokploy/dokploy:latest +# 4. Create the Postgres service +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 -# Installation +# 5. 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 + +# 6. Create the Traefik container +# Dokploy generates the Traefik configuration in /etc/dokploy/traefik +# on first boot, so give it a few seconds to start +sleep 10 + +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 ``` +Once everything is running, open `http://:3000` to access the Dokploy UI. + + + Ports **80**, **443**, and **3000** must be free. If your existing swarm already runs a reverse proxy bound to 80/443, you will need to free those ports or adjust the published ports of the `dokploy-traefik` container — Dokploy manages its own Traefik instance to route the domains of the applications you deploy. + + + + **Using your own Postgres?** You can skip step 4 and point Dokploy to an existing database instead: replace the `POSTGRES_PASSWORD_FILE` env var (and the `dokploy_postgres_password` secret) on the `dokploy` service with `-e DATABASE_URL=postgres://user:password@host:5432/dbname`. By default Dokploy connects to `dokploy-postgres:5432` with user and database `dokploy`; these defaults can also be overridden individually with `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, and `POSTGRES_DB`. + + ## Setup Dokploy Timezone To setup the timezone of Dokploy, you can use the following command: diff --git a/apps/docs/content/docs/core/troubleshooting.mdx b/apps/docs/content/docs/core/troubleshooting.mdx index 2ce4782..6d8730f 100644 --- a/apps/docs/content/docs/core/troubleshooting.mdx +++ b/apps/docs/content/docs/core/troubleshooting.mdx @@ -627,22 +627,16 @@ docker service create \ ### Recreate Dokploy Service -First, get the private IP of your server for the ADVERTISE_ADDR: - -```bash -# Get the private IP of your server (excludes Docker-created interfaces like docker0) -ip -o -4 addr show scope global | awk '$2 !~ /^(docker|br-|veth)/ {print $4}' | cut -d/ -f1 | grep -E "^(192\.168\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.)" | head -n1 -``` - -Copy the IP address from the output and use it in the command below. - 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 -` + + ```bash docker service rm dokploy # Create the dokploy service -# Replace with the IP you got from the command above docker service create \ --name dokploy \ --replicas 1 \ @@ -651,12 +645,13 @@ docker service create \ --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 ADVERTISE_ADDR= \ -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ + -e BETTER_AUTH_SECRET_FILE=/run/secrets/dokploy_auth_secret \ dokploy/dokploy:latest ``` @@ -671,13 +666,14 @@ docker service create \ --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 ADVERTISE_ADDR= \ -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ + -e BETTER_AUTH_SECRET_FILE=/run/secrets/dokploy_auth_secret \ dokploy/dokploy:latest ``` diff --git a/apps/website/public/install.sh b/apps/website/public/install.sh index dae65b3..43a100b 100644 --- a/apps/website/public/install.sh +++ b/apps/website/public/install.sh @@ -322,7 +322,6 @@ install_dokploy() { --constraint 'node.role == manager' \ $endpoint_mode \ $release_tag_env \ - -e ADVERTISE_ADDR=$advertise_addr \ -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ -e BETTER_AUTH_SECRET_FILE=/run/secrets/dokploy_auth_secret \ $DOCKER_IMAGE