Skip to content

Commit 1a8a911

Browse files
SiumauricioSiumauricio
committed
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.
1 parent 640b0de commit 1a8a911

File tree

4 files changed

+217
-26
lines changed

4 files changed

+217
-26
lines changed

‎apps/docs/content/docs/core/installation.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,64 @@ Dokploy utilizes Docker, so it is essential to have Docker installed on your ser
7777
curl -sSL https://dokploy.com/install.sh | sh
7878
```
7979

80+
### Advanced Installation Options
81+
82+
The installation script automatically detects and installs the latest stable version from GitHub. However, you can customize the installation using environment variables:
83+
84+
#### Install Specific Versions
85+
86+
**Install Canary Version (Development):**
87+
```bash
88+
export DOKPLOY_VERSION=canary && curl -sSL https://dokploy.com/install.sh | sh
89+
```
90+
91+
**Install Latest Stable:**
92+
```bash
93+
export DOKPLOY_VERSION=latest && curl -sSL https://dokploy.com/install.sh | sh
94+
```
95+
96+
**Install Specific Version:**
97+
```bash
98+
export DOKPLOY_VERSION=v0.26.6 && curl -sSL https://dokploy.com/install.sh | sh
99+
```
100+
101+
#### Custom Network Configuration
102+
103+
If you need to customize the Docker Swarm network configuration (useful to avoid CIDR conflicts with cloud provider VPCs):
104+
105+
```bash
106+
export DOCKER_SWARM_INIT_ARGS="--default-addr-pool 172.20.0.0/16 --default-addr-pool-mask-length 24"
107+
curl -sSL https://dokploy.com/install.sh | sh
108+
```
109+
110+
#### Manual Advertise Address
111+
112+
If the script cannot detect your server's IP automatically, specify it manually:
113+
114+
```bash
115+
export ADVERTISE_ADDR=192.168.1.100
116+
curl -sSL https://dokploy.com/install.sh | sh
117+
```
118+
119+
### Proxmox LXC Support
120+
121+
<Callout type='info'>
122+
The installation script automatically detects Proxmox LXC containers and applies the necessary configurations (`--endpoint-mode dnsrr`) for compatibility.
123+
</Callout>
124+
125+
### Updating Dokploy
126+
127+
To update your Dokploy installation to the latest version:
128+
129+
```bash
130+
curl -sSL https://dokploy.com/install.sh | sh -s update
131+
```
132+
133+
**Update to Specific Version:**
134+
```bash
135+
export DOKPLOY_VERSION=v0.26.6 && curl -sSL https://dokploy.com/install.sh | sh -s update
136+
```
137+
80138
## Completing the Setup
81139

82140
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:

‎apps/docs/content/docs/core/manual-installation.mdx‎

Lines changed: 65 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: 'Manual Installation'
33
description: 'Learn how to manually install Dokploy on your server.'
44
---
55

6-
If you wish to customize the Dokploy installation on your server, you can modify several enviroment variables:
6+
If you wish to customize the Dokploy installation on your server, you can modify several environment variables:
77

88
1. **PORT** - Ideal for avoiding conflicts with other services.
99
2. **TRAEFIK_SSL_PORT** - Set to another port if you want to use a different port for SSL.
@@ -134,13 +134,22 @@ install_dokploy() {
134134

135135
chmod 777 /etc/dokploy
136136

137+
# Generate secure random password for Postgres
138+
POSTGRES_PASSWORD=$(openssl rand -base64 32 | tr -d "=+/" | cut -c1-32)
139+
140+
# Store password as Docker Secret (encrypted and secure)
141+
echo "$POSTGRES_PASSWORD" | docker secret create dokploy_postgres_password - 2>/dev/null || true
142+
143+
echo "Generated secure database credentials (stored in Docker Secrets)"
144+
137145
docker service create \
138146
--name dokploy-postgres \
139147
--constraint 'node.role==manager' \
140148
--network dokploy-network \
141149
--env POSTGRES_USER=dokploy \
142150
--env POSTGRES_DB=dokploy \
143-
--env POSTGRES_PASSWORD=amukds4wi9001583845717ad2 \
151+
--secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \
152+
--env POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
144153
--mount type=volume,source=dokploy-postgres,target=/var/lib/postgresql/data \
145154
postgres:16
146155

@@ -151,9 +160,6 @@ install_dokploy() {
151160
--mount type=volume,source=dokploy-redis,target=/data \
152161
redis:7
153162

154-
docker pull traefik:v3.6.1
155-
docker pull dokploy/dokploy:latest
156-
157163
# Installation
158164
docker service create \
159165
--name dokploy \
@@ -162,11 +168,13 @@ install_dokploy() {
162168
--mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
163169
--mount type=bind,source=/etc/dokploy,target=/etc/dokploy \
164170
--mount type=volume,source=dokploy,target=/root/.docker \
171+
--secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \
165172
--publish published=3000,target=3000,mode=host \
166173
--update-parallelism 1 \
167174
--update-order stop-first \
168175
--constraint 'node.role == manager' \
169176
-e ADVERTISE_ADDR=$advertise_addr \
177+
-e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
170178
dokploy/dokploy:latest
171179

172180

@@ -258,6 +266,23 @@ To customize the --advertise-addr parameter, replace the line: `advertise_addr=$
258266
:warning: This IP address should be accessible to all nodes that will join the Swarm.
259267

260268

269+
## Proxmox LXC Considerations
270+
271+
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.
272+
273+
For manual installations in LXC, add this flag to your service creation commands:
274+
275+
```bash
276+
docker service create \
277+
--name dokploy-postgres \
278+
--endpoint-mode dnsrr \
279+
# ... rest of the configuration
280+
```
281+
282+
<Callout type='warn'>
283+
**Note:** The `--endpoint-mode dnsrr` flag is required for Docker services to work properly in Proxmox LXC containers due to networking limitations.
284+
</Callout>
285+
261286
## Existing Docker swarm
262287

263288
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:
303328
curl -sSL https://dokploy.com/install.sh | sh -s update
304329
```
305330

306-
To use a specific version, you can use the following command:
331+
### Version-Specific Installation & Updates
332+
333+
The installation script automatically detects the latest stable version from GitHub. You can also specify a particular version:
307334

335+
**Install/Update to Canary (Development):**
308336
```bash
309337
export DOKPLOY_VERSION=canary && curl -sSL https://dokploy.com/install.sh | sh
310-
export DOKPLOY_VERSION=feature && curl -sSL https://dokploy.com/install.sh | sh
311-
curl -sSL https://dokploy.com/install.sh | sh (defaults to latest)
312338
```
313339

314-
Alternatively, you can use `bash -s`:
340+
**Install/Update to Latest Stable:**
341+
```bash
342+
export DOKPLOY_VERSION=latest && curl -sSL https://dokploy.com/install.sh | sh
343+
```
344+
345+
**Install/Update to Specific Version:**
346+
```bash
347+
export DOKPLOY_VERSION=v0.26.6 && curl -sSL https://dokploy.com/install.sh | sh
348+
```
349+
350+
**Auto-detect Latest Stable (Default):**
351+
```bash
352+
curl -sSL https://dokploy.com/install.sh | sh
353+
```
354+
355+
Alternatively, you can use `bash -s` for inline version specification:
315356

316357
```bash
317358
DOKPLOY_VERSION=canary bash -s < <(curl -sSL https://dokploy.com/install.sh)
318-
DOKPLOY_VERSION=feature bash -s < <(curl -sSL https://dokploy.com/install.sh)
359+
DOKPLOY_VERSION=v0.26.6 bash -s < <(curl -sSL https://dokploy.com/install.sh)
360+
```
361+
362+
### Additional Environment Variables
363+
364+
**Custom Docker Swarm Network Configuration:**
365+
```bash
366+
export DOCKER_SWARM_INIT_ARGS="--default-addr-pool 172.20.0.0/16 --default-addr-pool-mask-length 24"
367+
curl -sSL https://dokploy.com/install.sh | sh
368+
```
369+
370+
**Manual Advertise Address:**
371+
```bash
372+
export ADVERTISE_ADDR=192.168.1.100
373+
curl -sSL https://dokploy.com/install.sh | sh
319374
```

‎apps/docs/content/docs/core/troubleshooting.mdx‎

Lines changed: 50 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -460,13 +460,18 @@ You should now be able to access the user interface.
460460

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

463+
<Callout type='warn'>
464+
**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.
465+
</Callout>
466+
467+
### Recreate Redis Service
463468

464-
Remove the dokploy-redis service:
469+
Remove and recreate the dokploy-redis service:
465470
```bash
466471
docker service rm dokploy-redis
467472

468473
# Create a new dokploy-redis service
469-
docker service create \
474+
docker service create \
470475
--name dokploy-redis \
471476
--constraint 'node.role==manager' \
472477
--network dokploy-network \
@@ -479,18 +484,23 @@ Remove the dokploy-postgres service:
479484
```bash
480485
docker service rm dokploy-postgres
481486

482-
# Create a new dokploy-postgres service
483-
docker service create \
487+
# Create a new dokploy-postgres service with Docker Secrets
488+
docker service create \
484489
--name dokploy-postgres \
485490
--constraint 'node.role==manager' \
486491
--network dokploy-network \
487492
--env POSTGRES_USER=dokploy \
488493
--env POSTGRES_DB=dokploy \
489-
--env POSTGRES_PASSWORD=amukds4wi9001583845717ad2 \
494+
--secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \
495+
--env POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
490496
--mount type=volume,source=dokploy-postgres,target=/var/lib/postgresql/data \
491497
postgres:16
492498
```
493499

500+
<Callout type='info'>
501+
**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.
502+
</Callout>
503+
494504

495505
Remove the dokploy-traefik service:
496506

@@ -528,33 +538,59 @@ docker service create \
528538
traefik:v3.6.1
529539
```
530540

531-
Remove the dokploy service:
541+
### Recreate Dokploy Service
532542

533-
```bash
534-
docker service rm dokploy
543+
First, get the private IP of your server for the ADVERTISE_ADDR:
535544

536-
# Create a new dokploy service
545+
```bash
546+
# Get the private IP of your server
547+
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
548+
```
537549

538-
# 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:
550+
Copy the IP address from the output and use it in the command below.
539551

540-
# Run this command to get the private IP of your server:
552+
Remove and recreate the dokploy service:
541553

542-
# Copy this value and paste in the ADVERTISE_ADDR variable:
543-
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
554+
```bash
555+
docker service rm dokploy
544556

545557
# Create the dokploy service
558+
# Replace <YOUR_PRIVATE_IP> with the IP you got from the command above
559+
docker service create \
560+
--name dokploy \
561+
--replicas 1 \
562+
--network dokploy-network \
563+
--mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
564+
--mount type=bind,source=/etc/dokploy,target=/etc/dokploy \
565+
--mount type=volume,source=dokploy,target=/root/.docker \
566+
--secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \
567+
--publish published=3000,target=3000,mode=host \
568+
--update-parallelism 1 \
569+
--update-order stop-first \
570+
--constraint 'node.role == manager' \
571+
-e ADVERTISE_ADDR=<YOUR_PRIVATE_IP> \
572+
-e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
573+
dokploy/dokploy:latest
574+
```
575+
576+
**For Proxmox LXC environments**, add the `--endpoint-mode dnsrr` flag to all services:
577+
578+
```bash
546579
docker service create \
547580
--name dokploy \
548581
--replicas 1 \
549582
--network dokploy-network \
550583
--mount type=bind,source=/var/run/docker.sock,target=/var/run/docker.sock \
551584
--mount type=bind,source=/etc/dokploy,target=/etc/dokploy \
552585
--mount type=volume,source=dokploy,target=/root/.docker \
586+
--secret source=dokploy_postgres_password,target=/run/secrets/postgres_password \
553587
--publish published=3000,target=3000,mode=host \
554588
--update-parallelism 1 \
555589
--update-order stop-first \
556590
--constraint 'node.role == manager' \
557-
-e ADVERTISE_ADDR="Eg: 192.168.1.100" \
591+
--endpoint-mode dnsrr \
592+
-e ADVERTISE_ADDR=<YOUR_PRIVATE_IP> \
593+
-e POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password \
558594
dokploy/dokploy:latest
559595
```
560596

0 commit comments

Comments
 (0)