From 1a8a91181a5ef8ec3b718220f8614a94763a05c8 Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Tue, 27 Jan 2026 14:08:44 -0600 Subject: [PATCH] docs: enhance installation and manual installation guides with advanced options and Docker Secrets - Added advanced installation options for specifying versions and custom network configurations in the installation documentation. - Updated the manual installation guide to include secure password generation for PostgreSQL using Docker Secrets. - Included Proxmox LXC considerations and emphasized the use of Docker Secrets for managing sensitive data. - Improved troubleshooting section with detailed steps for recreating services and managing environment variables. --- apps/docs/content/docs/core/installation.mdx | 58 ++++++++++++++ .../content/docs/core/manual-installation.mdx | 75 ++++++++++++++++--- .../content/docs/core/troubleshooting.mdx | 68 +++++++++++++---- apps/website/public/install.sh | 46 +++++++++++- 4 files changed, 219 insertions(+), 28 deletions(-) diff --git a/apps/docs/content/docs/core/installation.mdx b/apps/docs/content/docs/core/installation.mdx index 7123fed..bdabc3b 100644 --- a/apps/docs/content/docs/core/installation.mdx +++ b/apps/docs/content/docs/core/installation.mdx @@ -77,6 +77,64 @@ Dokploy utilizes Docker, so it is essential to have Docker installed on your ser curl -sSL https://dokploy.com/install.sh | sh ``` +### Advanced Installation Options + +The installation script automatically detects and installs the latest stable version from GitHub. However, you can customize the installation using environment variables: + +#### Install Specific Versions + +**Install Canary Version (Development):** +```bash +export DOKPLOY_VERSION=canary && curl -sSL https://dokploy.com/install.sh | sh +``` + +**Install Latest Stable:** +```bash +export DOKPLOY_VERSION=latest && curl -sSL https://dokploy.com/install.sh | sh +``` + +**Install Specific Version:** +```bash +export DOKPLOY_VERSION=v0.26.6 && curl -sSL https://dokploy.com/install.sh | sh +``` + +#### Custom Network Configuration + +If you need to customize the Docker Swarm network configuration (useful to avoid CIDR conflicts with cloud provider VPCs): + +```bash +export DOCKER_SWARM_INIT_ARGS="--default-addr-pool 172.20.0.0/16 --default-addr-pool-mask-length 24" +curl -sSL https://dokploy.com/install.sh | sh +``` + +#### Manual Advertise Address + +If the script cannot detect your server's IP automatically, specify it manually: + +```bash +export ADVERTISE_ADDR=192.168.1.100 +curl -sSL https://dokploy.com/install.sh | sh +``` + +### Proxmox LXC Support + + + The installation script automatically detects Proxmox LXC containers and applies the necessary configurations (`--endpoint-mode dnsrr`) for compatibility. + + +### Updating Dokploy + +To update your Dokploy installation to the latest version: + +```bash +curl -sSL https://dokploy.com/install.sh | sh -s update +``` + +**Update to Specific Version:** +```bash +export DOKPLOY_VERSION=v0.26.6 && curl -sSL https://dokploy.com/install.sh | sh -s update +``` + ## Completing the Setup After running the installation script, Dokploy and its dependencies will be set up on your server. Here's how to finalize the setup and start using Dokploy: diff --git a/apps/docs/content/docs/core/manual-installation.mdx b/apps/docs/content/docs/core/manual-installation.mdx index 40266d1..02e2929 100644 --- a/apps/docs/content/docs/core/manual-installation.mdx +++ b/apps/docs/content/docs/core/manual-installation.mdx @@ -3,7 +3,7 @@ title: 'Manual Installation' description: 'Learn how to manually install Dokploy on your server.' --- -If you wish to customize the Dokploy installation on your server, you can modify several enviroment variables: +If you wish to customize the Dokploy installation on your server, you can modify several environment variables: 1. **PORT** - Ideal for avoiding conflicts with other services. 2. **TRAEFIK_SSL_PORT** - Set to another port if you want to use a different port for SSL. @@ -134,13 +134,22 @@ install_dokploy() { chmod 777 /etc/dokploy + # Generate secure random password for Postgres + POSTGRES_PASSWORD=$(openssl rand -base64 32 | tr -d "=+/" | cut -c1-32) + + # Store password as Docker Secret (encrypted and secure) + echo "$POSTGRES_PASSWORD" | docker secret create dokploy_postgres_password - 2>/dev/null || true + + echo "Generated secure database credentials (stored in Docker Secrets)" + 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 \ + --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 @@ -151,9 +160,6 @@ install_dokploy() { --mount type=volume,source=dokploy-redis,target=/data \ redis:7 - docker pull traefik:v3.6.1 - docker pull dokploy/dokploy:latest - # Installation docker service create \ --name dokploy \ @@ -162,11 +168,13 @@ install_dokploy() { --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 \ --publish published=3000,target=3000,mode=host \ --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 @@ -258,6 +266,23 @@ To customize the --advertise-addr parameter, replace the line: `advertise_addr=$ :warning: This IP address should be accessible to all nodes that will join the Swarm. +## Proxmox LXC Considerations + +If you're installing Dokploy in a Proxmox LXC container, the installation script automatically detects the environment and adds `--endpoint-mode dnsrr` to Docker services for compatibility. + +For manual installations in LXC, add this flag to your service creation commands: + +```bash +docker service create \ + --name dokploy-postgres \ + --endpoint-mode dnsrr \ + # ... rest of the configuration +``` + + + **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 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: @@ -303,17 +328,47 @@ To upgrade Dokploy manually, you can use the following command: curl -sSL https://dokploy.com/install.sh | sh -s update ``` -To use a specific version, you can use the following command: +### Version-Specific Installation & Updates +The installation script automatically detects the latest stable version from GitHub. You can also specify a particular version: + +**Install/Update to Canary (Development):** ```bash export DOKPLOY_VERSION=canary && curl -sSL https://dokploy.com/install.sh | sh -export DOKPLOY_VERSION=feature && curl -sSL https://dokploy.com/install.sh | sh -curl -sSL https://dokploy.com/install.sh | sh (defaults to latest) ``` -Alternatively, you can use `bash -s`: +**Install/Update to Latest Stable:** +```bash +export DOKPLOY_VERSION=latest && curl -sSL https://dokploy.com/install.sh | sh +``` + +**Install/Update to Specific Version:** +```bash +export DOKPLOY_VERSION=v0.26.6 && curl -sSL https://dokploy.com/install.sh | sh +``` + +**Auto-detect Latest Stable (Default):** +```bash +curl -sSL https://dokploy.com/install.sh | sh +``` + +Alternatively, you can use `bash -s` for inline version specification: ```bash DOKPLOY_VERSION=canary bash -s < <(curl -sSL https://dokploy.com/install.sh) -DOKPLOY_VERSION=feature bash -s < <(curl -sSL https://dokploy.com/install.sh) +DOKPLOY_VERSION=v0.26.6 bash -s < <(curl -sSL https://dokploy.com/install.sh) +``` + +### Additional Environment Variables + +**Custom Docker Swarm Network Configuration:** +```bash +export DOCKER_SWARM_INIT_ARGS="--default-addr-pool 172.20.0.0/16 --default-addr-pool-mask-length 24" +curl -sSL https://dokploy.com/install.sh | sh +``` + +**Manual Advertise Address:** +```bash +export ADVERTISE_ADDR=192.168.1.100 +curl -sSL https://dokploy.com/install.sh | sh ``` diff --git a/apps/docs/content/docs/core/troubleshooting.mdx b/apps/docs/content/docs/core/troubleshooting.mdx index a3564ca..830a457 100644 --- a/apps/docs/content/docs/core/troubleshooting.mdx +++ b/apps/docs/content/docs/core/troubleshooting.mdx @@ -460,13 +460,18 @@ You should now be able to access the user interface. 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. + -Remove the dokploy-redis service: +### Recreate Redis Service + +Remove and recreate the dokploy-redis service: ```bash docker service rm dokploy-redis # Create a new dokploy-redis service - docker service create \ +docker service create \ --name dokploy-redis \ --constraint 'node.role==manager' \ --network dokploy-network \ @@ -479,18 +484,23 @@ Remove the dokploy-postgres service: ```bash docker service rm dokploy-postgres -# Create a new dokploy-postgres service - docker service create \ +# 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 \ - --env POSTGRES_PASSWORD=amukds4wi9001583845717ad2 \ + --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. + + Remove the dokploy-traefik service: @@ -528,21 +538,24 @@ docker service create \ traefik:v3.6.1 ``` -Remove the dokploy service: +### Recreate Dokploy Service + +First, get the private IP of your server for the ADVERTISE_ADDR: + +```bash +# Get the private IP of your server +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 +``` + +Copy the IP address from the output and use it in the command below. + +Remove and recreate 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 +# Replace with the IP you got from the command above docker service create \ --name dokploy \ --replicas 1 \ @@ -550,11 +563,34 @@ docker service create \ --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 \ --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" \ + -e ADVERTISE_ADDR= \ + -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ + dokploy/dokploy:latest +``` + +**For Proxmox LXC environments**, add the `--endpoint-mode dnsrr` flag to all services: + +```bash +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 \ + --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 \ dokploy/dokploy:latest ``` diff --git a/apps/website/public/install.sh b/apps/website/public/install.sh index d143bfd..21e7466 100644 --- a/apps/website/public/install.sh +++ b/apps/website/public/install.sh @@ -47,6 +47,37 @@ is_proxmox_lxc() { return 1 # Not LXC } +generate_random_password() { + # Generate a secure random password using multiple methods with fallbacks + local password="" + + # Try using openssl (most reliable, available on most systems) + if command -v openssl >/dev/null 2>&1; then + password=$(openssl rand -base64 32 | tr -d "=+/" | cut -c1-32) + # Fallback to /dev/urandom with tr (most Linux systems) + elif [ -r /dev/urandom ]; then + password=$(tr -dc 'A-Za-z0-9' < /dev/urandom | head -c 32) + # Last resort fallback using date and simple hashing + else + if command -v sha256sum >/dev/null 2>&1; then + password=$(date +%s%N | sha256sum | base64 | head -c 32) + elif command -v shasum >/dev/null 2>&1; then + password=$(date +%s%N | shasum -a 256 | base64 | head -c 32) + else + # Very basic fallback - combines multiple sources of entropy + password=$(echo "$(date +%s%N)-$(hostname)-$$-$RANDOM" | base64 | tr -d "=+/" | head -c 32) + fi + fi + + # Ensure we got a password of correct length + if [ -z "$password" ] || [ ${#password} -lt 20 ]; then + echo "Error: Failed to generate random password" >&2 + exit 1 + fi + + echo "$password" +} + install_dokploy() { # Detect version tag VERSION_TAG=$(detect_version) @@ -199,13 +230,22 @@ install_dokploy() { chmod 777 /etc/dokploy + # Generate secure random password for Postgres + POSTGRES_PASSWORD=$(generate_random_password) + + # Store password as Docker Secret (encrypted and secure) + echo "$POSTGRES_PASSWORD" | docker secret create dokploy_postgres_password - 2>/dev/null || true + + echo "Generated secure database credentials (stored in Docker Secrets)" + 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 \ + --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 \ $endpoint_mode \ postgres:16 @@ -232,6 +272,7 @@ install_dokploy() { --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 \ --publish published=3000,target=3000,mode=host \ --update-parallelism 1 \ --update-order stop-first \ @@ -239,6 +280,7 @@ install_dokploy() { $endpoint_mode \ $release_tag_env \ -e ADVERTISE_ADDR=$advertise_addr \ + -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \ $DOCKER_IMAGE sleep 4 @@ -315,4 +357,4 @@ if [ "$1" = "update" ]; then update_dokploy else install_dokploy -fi +fi \ No newline at end of file