DEV Community

Cover image for Dokploy Setup Guide
Subham
Subham

Posted on

Dokploy Setup Guide

#docker #devops #ai #development

Dokploy Setup Guide — Ubuntu & AlmaLinux

What is Dokploy?
Dokploy is a free, self-hosted PaaS — your own Vercel/Heroku running on your VPS. It bundles Docker Swarm, Traefik (SSL + routing), PostgreSQL, and Redis into one web dashboard. Deploy apps, manage databases, and handle domains all from a single UI.

Jump to your OS:

✅ Versions Verified (March 2026)

Component Version
Dokploy 0.28.6+
Docker Engine 29.3.0
Docker Compose 5.1.0
Traefik (bundled by Dokploy) 3.6.7
PostgreSQL (bundled by Dokploy) 16
Redis (bundled by Dokploy) 7

✅ Minimum Server Requirements

Resource Minimum Recommended
RAM 2 GB 4 GB
CPU 2 vCPU 2 vCPU
Disk 30 GB 50 GB

✅ Required Ports

⚠️ The Dokploy installation will fail if any of these ports are already in use.

Port Purpose
22 SSH — keep this open or you'll lose server access
80 HTTP traffic handled by Traefik
443 HTTPS traffic handled by Traefik
3000 Dokploy web UI

🟠 Ubuntu Guide

Tested on: Ubuntu 24.04 LTS, Ubuntu 22.04 LTS, Ubuntu 20.04 LTS

1️⃣ First Step — Connect to Your VPS

✅ 1. Get Your Credentials from Your Hosting Provider

  • IP address: YOUR_SERVER_IP
  • Username: root
  • Password: YOUR_PASSWORD

✅ 2. Connect via Terminal

ssh root@YOUR_SERVER_IP
Enter fullscreen mode Exit fullscreen mode

✅ 3. Accept the Host Key

Are you sure you want to continue connecting (yes/no/[fingerprint])?
Enter fullscreen mode Exit fullscreen mode

Type yes and press Enter.

✅ 4. Enter Your Password When Prompted

root@YOUR_SERVER_IP's password:
Enter fullscreen mode Exit fullscreen mode

Paste your password and press Enter. No characters appear while typing — that is normal.

✅ 5. You're In

root@your-hostname:~#
Enter fullscreen mode Exit fullscreen mode

2️⃣ Second Step — Prepare the System

✅ 1. Clear the Terminal

clear
Enter fullscreen mode Exit fullscreen mode

✅ 2. Confirm Your OS

lsb_release -a
Enter fullscreen mode Exit fullscreen mode

Expected:

Distributor ID: Ubuntu
Description:    Ubuntu 22.04.x LTS
Enter fullscreen mode Exit fullscreen mode

✅ 3. Update Package List

sudo apt update
Enter fullscreen mode Exit fullscreen mode

✅ 4. Upgrade All Packages

sudo apt upgrade -y
Enter fullscreen mode Exit fullscreen mode

If a configuration prompt appears, press Tab to select OK and press Enter.

✅ 5. Install Essential Tools

sudo apt install -y curl wget ca-certificates
Enter fullscreen mode Exit fullscreen mode

✅ 6. Reboot If a Kernel Update Was Applied

sudo reboot
Enter fullscreen mode Exit fullscreen mode

Reconnect via SSH after the server comes back up.

3️⃣ Third Step — Install Docker

On Ubuntu, Dokploy's installer can handle Docker automatically. Installing it yourself first is the safer and more controlled approach.

✅ 1. Remove Any Conflicting Old Docker Packages

sudo apt remove -y docker docker-engine docker.io containerd runc
Enter fullscreen mode Exit fullscreen mode

It's fine if none are installed — this will just report "not found".

✅ 2. Add Docker's Official GPG Key

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg
Enter fullscreen mode Exit fullscreen mode

✅ 3. Add the Docker Repository

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
Enter fullscreen mode Exit fullscreen mode

✅ 4. Install Docker Engine and Compose Plugin

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Enter fullscreen mode Exit fullscreen mode

✅ 5. Enable Docker to Start on Boot and Start It Now

sudo systemctl enable --now docker
Enter fullscreen mode Exit fullscreen mode

✅ 6. Verify the Installation

docker --version
docker compose version
Enter fullscreen mode Exit fullscreen mode

Expected:

Docker version 29.x.x, build ...
Docker Compose version v5.x.x
Enter fullscreen mode Exit fullscreen mode

✅ 7. Run a Quick Test

docker run hello-world
Enter fullscreen mode Exit fullscreen mode

You should see Hello from Docker! in the output. Docker is ready.

4️⃣ Fourth Step — Configure the Firewall

⚠️ Always open port 22 (SSH) before enabling ufw. If you enable the firewall without allowing SSH first, you will be locked out of the server.

✅ 1. Check Current Firewall Status

sudo ufw status
Enter fullscreen mode Exit fullscreen mode

✅ 2. Allow SSH First (Critical Step)

sudo ufw allow 22/tcp
Enter fullscreen mode Exit fullscreen mode

✅ 3. Allow the Remaining Required Ports

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3000/tcp
Enter fullscreen mode Exit fullscreen mode

✅ 4. Enable the Firewall

sudo ufw enable
Enter fullscreen mode Exit fullscreen mode

Type y and press Enter when prompted. Your SSH connection will remain active because port 22 was already allowed.

✅ 5. Verify All Rules Are Active

sudo ufw status numbered
Enter fullscreen mode Exit fullscreen mode

Expected:

Status: active

     To                         Action      From
     --                         ------      ----
[ 1] 22/tcp                     ALLOW IN    Anywhere
[ 2] 80/tcp                     ALLOW IN    Anywhere
[ 3] 443/tcp                    ALLOW IN    Anywhere
[ 4] 3000/tcp                   ALLOW IN    Anywhere
Enter fullscreen mode Exit fullscreen mode

5️⃣ Fifth Step — Install Dokploy

✅ 1. Run the Official Installer

curl -sSL https://dokploy.com/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

The installer will:

  • Initialize Docker Swarm on this server
  • Create the dokploy-network overlay network
  • Deploy dokploy — the web panel
  • Deploy dokploy-postgres — PostgreSQL 16 (Dokploy's own internal database)
  • Deploy dokploy-redis — Redis 7 (Dokploy's own deployment queue)
  • Deploy dokploy-traefik — the reverse proxy for routing and SSL

✅ 2. Wait for the Services to Start
The installer will print:

Congratulations, Dokploy is installed!
Wait 15 seconds for the server to start
Please go to http://YOUR_SERVER_IP:3000
Enter fullscreen mode Exit fullscreen mode

Wait the full 15 seconds before opening the browser.

✅ 3. Confirm All Services Are Running

docker service ls
Enter fullscreen mode Exit fullscreen mode

Every service must show 1/1 under REPLICAS:

NAME               MODE         REPLICAS   IMAGE
dokploy            replicated   1/1        dokploy/dokploy:latest
dokploy-postgres   replicated   1/1        postgres:16
dokploy-redis      replicated   1/1        redis:7
dokploy-traefik    replicated   1/1        traefik:v3.x
Enter fullscreen mode Exit fullscreen mode

✅ 4. Confirm the Panel Responds

curl -I http://127.0.0.1:3000/
Enter fullscreen mode Exit fullscreen mode

Expected:

HTTP/1.1 302 Found
Location: /register
Enter fullscreen mode Exit fullscreen mode

6️⃣ Sixth Step — Create Your Admin Account

✅ 1. Open the Panel in Your Browser

http://YOUR_SERVER_IP:3000
Enter fullscreen mode Exit fullscreen mode

You will be redirected to the registration page.

✅ 2. Register the Admin Account
Fill in your email and a strong password, then click Create Account. This is the only account with full admin access — store the credentials securely.

✅ 3. Explore the Dashboard

  • Projects — create and manage apps and databases
  • Settings → Server — configure your domain and SSL
  • Settings → Destinations — configure S3 backup storage

7️⃣ Seventh Step — Point a Domain to Dokploy

✅ 1. Add DNS Records at Your Domain Provider

Type Name Value TTL
A @ YOUR_SERVER_IP 1 hour
A www YOUR_SERVER_IP 1 hour

For a subdomain panel (e.g. panel.xyz.com) add A with name panel.

✅ 2. Verify DNS Propagation 

nslookup yourdomain.com
Enter fullscreen mode Exit fullscreen mode

Expected:

Name:    yourdomain.com
Address: YOUR_SERVER_IP
Enter fullscreen mode Exit fullscreen mode

DNS can take up to 48 hours globally, but usually resolves in 5–30 minutes.

✅ 3. Set the Domain Inside Dokploy

  1. Go to Settings → Server
  2. Enter your domain under Dokploy Panel Domain
  3. Select Let's Encrypt
  4. Enter your email address for SSL notifications
  5. Click Save

Dokploy's built-in Traefik will automatically request and renew the certificate.

✅ 4. Verify HTTPS Is Working 

https://yourdomain.com
Enter fullscreen mode Exit fullscreen mode

You should see the Dokploy login page with a padlock in the browser address bar.

✅ 5. (Optional) Remove Direct IP Access

After confirming HTTPS works on your domain:

docker service update --publish-rm "published=3000,target=3000,mode=host" dokploy
Enter fullscreen mode Exit fullscreen mode

⚠️ Only run this after your domain and HTTPS are fully confirmed. Running it before means losing panel access.

8️⃣ Eighth Step — Set Up PostgreSQL for Your App

Dokploy runs its own internal PostgreSQL instance for its own data. The one you create here is completely separate — it is your application's database.

✅ 1. Create a Project

  1. Click Projects → New Project
  2. Enter a name (e.g. my-app) → Click Create

✅ 2. Add a PostgreSQL Database

  1. Inside the project → Create New Service → Database → PostgreSQL
  2. Fill in the fields:
Field Example Value
Service Name my-app-db
Database Name myapp
Database User myapp_user
Database Password StrongPass@2025
PostgreSQL Version 16
  1. Click Create

✅ 3. Deploy the Database

Go to the General tab → Click Deploy → Wait for the status to turn green (Running)

✅ 4. Get the Internal Connection Strings

The Internal Host shown in the Dokploy UI is the service name. Use it exactly as the hostname in your app's environment variables:

DB_HOST=my-app-db
DB_PORT=5432
DB_NAME=myapp
DB_USER=myapp_user
DB_PASSWORD=StrongPass@2025
DATABASE_URL=postgresql://myapp_user:StrongPass@2025@my-app-db:5432/myapp
Enter fullscreen mode Exit fullscreen mode

⚠️ Use the service name my-app-db as the host — never localhost or the server IP. Services inside the same Dokploy project communicate with each other via their service names over the internal Docker Swarm network.

✅ 5. (Optional) Expose Externally for pgAdmin or TablePlus

  1. Open your PostgreSQL service → General tab
  2. Under External Credentials, enter an External Port (e.g. 5433)
  3. Click Save
  4. Open that port in the firewall: 
   sudo ufw allow 5433/tcp
Enter fullscreen mode Exit fullscreen mode
  1. Connect from your local machine: 
   Host: YOUR_SERVER_IP | Port: 5433
   Database: myapp      | User: myapp_user
   Password: StrongPass@2025
Enter fullscreen mode Exit fullscreen mode

9️⃣ Ninth Step — Set Up Redis for Your App

Dokploy runs its own internal Redis for managing its deployment queue. The one you create here is completely separate — it is your application's cache/session/queue store.

✅ 1. Add a Redis Service

  1. Inside your project → Create New Service → Database → Redis
  2. Fill in:
Field Example Value
Service Name my-app-cache
Redis Password RedisPass@2025
Redis Version 7
  1. Click Create

✅ 2. Deploy Redis

Go to the General tab → Click Deploy → Wait for Running (green)

✅ 3. Get the Internal Connection Strings 

REDIS_HOST=my-app-cache
REDIS_PORT=6379
REDIS_PASSWORD=RedisPass@2025
REDIS_URL=redis://:RedisPass@2025@my-app-cache:6379
Enter fullscreen mode Exit fullscreen mode

Redis supports database numbers 0–15. Use them to separate concerns:

CACHE_URL=redis://:RedisPass@2025@my-app-cache:6379/0
SESSION_URL=redis://:RedisPass@2025@my-app-cache:6379/1
QUEUE_URL=redis://:RedisPass@2025@my-app-cache:6379/2
Enter fullscreen mode Exit fullscreen mode

✅ 4. (Optional) Expose Externally for RedisInsight

  1. Open your Redis service → General tab
  2. Under External Credentials, enter External Port 6379
  3. Click Save
  4. Open the port: 
   sudo ufw allow 6379/tcp
Enter fullscreen mode Exit fullscreen mode
  1. In RedisInsight, connect with:
    • Host: YOUR_SERVER_IP | Port: 6379
    • Username: default | Password: RedisPass@2025

🔟 Tenth Step — Deploy Your Application

✅ 1. Add an Application Service

Inside your project → Create New Service → Application

Choose a source:

  • GitHub / GitLab — connects your repo with auto CI/CD on every push
  • Docker Compose — upload your own docker-compose.yml
  • Docker Image — pull from Docker Hub or any registry

✅ 2. Set Environment Variables

In the Environment tab, add your connection strings:

DATABASE_URL=postgresql://myapp_user:StrongPass@2025@my-app-db:5432/myapp
REDIS_URL=redis://:RedisPass@2025@my-app-cache:6379
PORT=3333
NODE_ENV=production
Enter fullscreen mode Exit fullscreen mode

Click Save.

✅ 3. Configure a Domain

  1. Domains tab → Add Domain
  2. Enter your app's subdomain (e.g. app.yourdomain.com)
  3. Set Container Port to whatever your app listens on (e.g. 3333)
  4. Select Let's Encrypt → Click Save

Make sure app.yourdomain.com has an A record pointing to your server IP.

✅ 4. Deploy and Verify

General tab → Deploy → Watch the live logs → Visit https://app.yourdomain.com

📝 Ubuntu Troubleshooting

⭐ Port 3000 Not Accessible 

sudo ufw status
sudo ufw allow 3000/tcp
docker service ls
docker ps | grep dokploy
Enter fullscreen mode Exit fullscreen mode

⭐ SSL Certificate Not Issued 

# Check Traefik logs for Let's Encrypt errors
docker logs $(docker ps -q -f name=dokploy_dokploy-traefik) 2>&1 | tail -50

# Confirm ports 80 and 443 are open
sudo ufw status

# Confirm DNS resolves to this server
nslookup yourdomain.com
Enter fullscreen mode Exit fullscreen mode

⭐ App Cannot Reach the Database or Redis

The service name must be used — never localhost:

# WRONG
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
# CORRECT
DATABASE_URL=postgresql://user:pass@my-app-db:5432/mydb
Enter fullscreen mode Exit fullscreen mode

Verify all services share the same network:

docker network inspect dokploy-network
Enter fullscreen mode Exit fullscreen mode

⭐ Docker Does Not Start After Reboot 

sudo systemctl enable docker
sudo systemctl start docker
sudo systemctl status docker
Enter fullscreen mode Exit fullscreen mode

🔵 AlmaLinux Guide

Tested on: AlmaLinux 9.x, AlmaLinux 10.x

⚠️ Two things that differ from Ubuntu and will cause failures if skipped:

1. firewalld must be started manually.
On many VPS providers, firewalld is installed but disabled. Running firewall-cmd commands without starting the service first means the rules are written to disk but never enforced — then when --reload is finally called, it activates firewalld for the first time and resets your SSH connection.
Always enable and start firewalld before running any firewall-cmd rule.

2. Docker must be installed manually before Dokploy.
Dokploy's bundled Docker install script uses Docker's convenience helper which returns Unsupported distribution 'almalinux' and the Dokploy installation fails entirely. Install Docker from Docker's official CentOS/RHEL repository first. Step 3 covers this exactly.

1️⃣ First Step — Connect to Your VPS

✅ 1. Get Your Credentials from Your Hosting Provider

  • IP address: YOUR_SERVER_IP
  • Username: root
  • Password: YOUR_PASSWORD

✅ 2. Connect via Terminal

ssh root@YOUR_SERVER_IP
Enter fullscreen mode Exit fullscreen mode

✅ 3. Accept the Host Key

Are you sure you want to continue connecting (yes/no/[fingerprint])?
Enter fullscreen mode Exit fullscreen mode

Type yes and press Enter.

✅ 4. Enter Your Password When Prompted

root@YOUR_SERVER_IP's password:
Enter fullscreen mode Exit fullscreen mode

Paste your password and press Enter. No characters appear while typing — that is normal.

✅ 5. You're In

[root@your-hostname ~]#
Enter fullscreen mode Exit fullscreen mode

2️⃣ Second Step — Prepare the System

✅ 1. Clear the Terminal

clear
Enter fullscreen mode Exit fullscreen mode

✅ 2. Confirm Your OS

cat /etc/os-release
Enter fullscreen mode Exit fullscreen mode

Expected:

NAME="AlmaLinux"
VERSION="9.x (Seafoam Ocelot)"
ID="almalinux"
ID_LIKE="rhel centos fedora"
Enter fullscreen mode Exit fullscreen mode

✅ 3. Enable the EPEL Repository
EPEL (Extra Packages for Enterprise Linux) is required for several packages on AlmaLinux:

sudo dnf install -y epel-release
Enter fullscreen mode Exit fullscreen mode

✅ 4. Check for Available Updates

sudo dnf check-update
Enter fullscreen mode Exit fullscreen mode

Exit code 100 is normal — it means updates are available.

✅ 5. Apply All Updates

sudo dnf upgrade -y
Enter fullscreen mode Exit fullscreen mode

✅ 6. Install Essential Tools

sudo dnf install -y curl wget ca-certificates dnf-plugins-core
Enter fullscreen mode Exit fullscreen mode

✅ 7. Reboot If a Kernel Update Was Applied

sudo reboot
Enter fullscreen mode Exit fullscreen mode

Reconnect via SSH after the server comes back up.

3️⃣ Third Step — Install Docker (Mandatory Before Dokploy on AlmaLinux)

⚠️ Do not skip this step and do not run the Dokploy installer before completing it.

Dokploy's built-in Docker setup uses Docker's convenience install script. On AlmaLinux that script exits with:

ERROR: Unsupported distribution 'almalinux'

The fix is to install Docker yourself from Docker's official CentOS repository, which AlmaLinux is fully binary-compatible with. Once Docker is present on the system, the Dokploy installer detects it and skips its own Docker step.

✅ 1. Remove Any Old or Conflicting Docker Packages

sudo dnf remove -y docker docker-client docker-client-latest docker-common \
  docker-latest docker-latest-logrotate docker-logrotate docker-engine
Enter fullscreen mode Exit fullscreen mode

If none are installed this command just exits cleanly.

✅ 2. Add Docker's Official Repository
AlmaLinux uses the same repository as CentOS/RHEL:

sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
Enter fullscreen mode Exit fullscreen mode

✅ 3. Install Docker Engine and Compose Plugin

sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Enter fullscreen mode Exit fullscreen mode

When prompted to accept a GPG key, type y and press Enter.

✅ 4. Enable Docker to Start on Boot and Start It Now
On AlmaLinux, services do not auto-start after installation. You must enable them explicitly:

sudo systemctl enable --now docker
Enter fullscreen mode Exit fullscreen mode

✅ 5. Verify the Installation

docker --version
docker compose version
Enter fullscreen mode Exit fullscreen mode

Expected (verified on real AlmaLinux 10.1 server, March 2026):

Docker version 29.3.0, build ...
Docker Compose version v5.1.0
Enter fullscreen mode Exit fullscreen mode

✅ 6. Run a Quick Test

docker run hello-world
Enter fullscreen mode Exit fullscreen mode

You should see Hello from Docker!. Docker is ready. The Dokploy installer will now succeed.

4️⃣ Fourth Step — Configure the Firewall

⚠️ AlmaLinux uses firewalld, not ufw. All firewall commands use firewall-cmd.

The most important rule: start and enable firewalld before running any firewall-cmd commands. If firewalld is not running when you call --reload, that command starts the service for the first time, enforces the new rules, and your SSH session drops because the --permanent rules you added were incomplete at that point.

The order is: start firewalld → confirm SSH is allowed → add ports → reload.

✅ 1. Enable and Start firewalld

sudo systemctl enable firewalld
sudo systemctl start firewalld
Enter fullscreen mode Exit fullscreen mode

✅ 2. Confirm firewalld Is Active

sudo systemctl status firewalld
Enter fullscreen mode Exit fullscreen mode

Look for Active: active (running):

● firewalld.service - firewalld - dynamic firewall daemon
     Loaded: loaded (/usr/lib/systemd/system/firewalld.service; enabled; ...)
     Active: active (running) since ...
Enter fullscreen mode Exit fullscreen mode

✅ 3. Check What the Default Zone Already Allows

sudo firewall-cmd --list-all
Enter fullscreen mode Exit fullscreen mode

The public zone includes ssh by default. You will see a line like:

services: cockpit dhcpv6-client ssh
Enter fullscreen mode Exit fullscreen mode

⚠️ This is the output of the command — it shows which services are currently allowed. Do not run cockpit dhcpv6-client ssh as a command. It is not a command, it is information.

✅ 4. Explicitly Persist SSH as a Permanent Rule (Safety Step)
Even though SSH is in the default zone, make it permanent so it survives any zone resets:

sudo firewall-cmd --permanent --add-service=ssh
Enter fullscreen mode Exit fullscreen mode

✅ 5. Open the Remaining Required Ports

sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=3000/tcp
Enter fullscreen mode Exit fullscreen mode

✅ 6. Reload firewalld to Enforce All Rules

sudo firewall-cmd --reload
Enter fullscreen mode Exit fullscreen mode

Your SSH session will stay connected because SSH was explicitly made permanent in step 4 before this reload.

✅ 7. Verify Open Ports and Services

sudo firewall-cmd --list-ports
sudo firewall-cmd --list-services
Enter fullscreen mode Exit fullscreen mode

Expected ports:

80/tcp 443/tcp 3000/tcp
Enter fullscreen mode Exit fullscreen mode

Expected services (SSH must be listed):

cockpit dhcpv6-client ssh
Enter fullscreen mode Exit fullscreen mode

✅ 8. Allow SELinux Network Connections (AlmaLinux Specific)
AlmaLinux runs SELinux in enforcing mode by default. Without this, containers cannot make outbound network connections:

sudo setsebool -P httpd_can_network_connect 1
Enter fullscreen mode Exit fullscreen mode

Confirm it is set:

getsebool httpd_can_network_connect
Enter fullscreen mode Exit fullscreen mode

Expected:

httpd_can_network_connect --> on
Enter fullscreen mode Exit fullscreen mode

5️⃣ Fifth Step — Install Dokploy

✅ 1. Set the Advertise Address
The Dokploy installer cannot always auto-detect the IP on AlmaLinux. Set it manually before running the installer:

export ADVERTISE_ADDR="YOUR_SERVER_IP"
Enter fullscreen mode Exit fullscreen mode

Replace with your actual VPS IP.

✅ 2. (Optional) Pin the Dokploy Version
To install a specific verified version (recommended for stability):

export DOKPLOY_VERSION="v0.28.6"
Enter fullscreen mode Exit fullscreen mode

Skip this to get the latest stable version automatically.

✅ 3. Run the Official Dokploy Installer

curl -sSL https://dokploy.com/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

Because Docker is already installed, the installer skips its own Docker step and goes straight to deploying the Dokploy platform services:

  • dokploy — the web panel
  • dokploy-postgres — PostgreSQL 16 (Dokploy's own internal database)
  • dokploy-redis — Redis 7 (Dokploy's own deployment queue)
  • dokploy-traefik — reverse proxy for routing and SSL

✅ 4. Wait for All Services to Start
The installer will print:

Congratulations, Dokploy is installed!
Wait 15 seconds for the server to start
Please go to http://YOUR_SERVER_IP:3000
Enter fullscreen mode Exit fullscreen mode

Wait the full 15 seconds before opening the browser.

✅ 5. Confirm All Services Are Running

docker service ls
Enter fullscreen mode Exit fullscreen mode

Every service must show 1/1 under REPLICAS:

NAME               MODE         REPLICAS   IMAGE
dokploy            replicated   1/1        dokploy/dokploy:latest
dokploy-postgres   replicated   1/1        postgres:16
dokploy-redis      replicated   1/1        redis:7
dokploy-traefik    replicated   1/1        traefik:v3.6.7
Enter fullscreen mode Exit fullscreen mode

✅ 6. Confirm the Panel Responds

curl -I http://127.0.0.1:3000/
Enter fullscreen mode Exit fullscreen mode

Expected:

HTTP/1.1 302 Found
Location: /register
Enter fullscreen mode Exit fullscreen mode

6️⃣ Sixth Step — Create Your Admin Account

✅ 1. Open the Panel in Your Browser

http://YOUR_SERVER_IP:3000
Enter fullscreen mode Exit fullscreen mode

You will be redirected to the registration page.

✅ 2. Register the Admin Account
Fill in your email and a strong password, then click Create Account. This is the only account with full admin access — store the credentials securely.

✅ 3. Explore the Dashboard

  • Projects — create and manage apps and databases
  • Settings → Server — configure your domain and SSL
  • Settings → Destinations — configure S3 backup storage

7️⃣ Seventh Step — Point a Domain to Dokploy

✅ 1. Add DNS Records at Your Domain Provider

Type Name Value TTL
A @ YOUR_SERVER_IP 1 hour
A www YOUR_SERVER_IP 1 hour

For a subdomain panel (e.g. panel.xyz.com) add A with name panel.

✅ 2. Verify DNS Propagation 

nslookup yourdomain.com
Enter fullscreen mode Exit fullscreen mode

Expected:

Name:    yourdomain.com
Address: YOUR_SERVER_IP
Enter fullscreen mode Exit fullscreen mode

DNS can take up to 48 hours globally, but usually resolves in 5–30 minutes.

✅ 3. Set the Domain Inside Dokploy

  1. Go to Settings → Server
  2. Enter your domain under Dokploy Panel Domain
  3. Select Let's Encrypt
  4. Enter your email address for SSL notifications
  5. Click Save

Dokploy's Traefik will automatically request and renew the certificate.

✅ 4. Verify HTTPS Is Working 

https://yourdomain.com
Enter fullscreen mode Exit fullscreen mode

You should see the Dokploy login page with a padlock in the browser address bar.

✅ 5. (Optional) Remove Direct IP Access

After confirming HTTPS works on your domain:

docker service update --publish-rm "published=3000,target=3000,mode=host" dokploy
Enter fullscreen mode Exit fullscreen mode

⚠️ Only run this after your domain and HTTPS are fully confirmed.

8️⃣ Eighth Step — Set Up PostgreSQL for Your App

Dokploy runs its own internal PostgreSQL for its own data. The one you create here is completely separate — it is your application's database.

✅ 1. Create a Project

  1. Click Projects → New Project
  2. Enter a name (e.g. my-app) → Click Create

✅ 2. Add a PostgreSQL Database

  1. Inside the project → Create New Service → Database → PostgreSQL
  2. Fill in the fields:
Field Example Value
Service Name my-app-db
Database Name myapp
Database User myapp_user
Database Password StrongPass@2025
PostgreSQL Version 16
  1. Click Create

✅ 3. Deploy the Database

Go to the General tab → Click Deploy → Wait for the status to turn green (Running)

✅ 4. Get the Internal Connection Strings

The Internal Host shown in the Dokploy UI is the service name. Use it as the hostname in your app's environment variables:

DB_HOST=my-app-db
DB_PORT=5432
DB_NAME=myapp
DB_USER=myapp_user
DB_PASSWORD=StrongPass@2025
DATABASE_URL=postgresql://myapp_user:StrongPass@2025@my-app-db:5432/myapp
Enter fullscreen mode Exit fullscreen mode

⚠️ Use the service name my-app-db as the host — never localhost or the server IP. Services inside the same Dokploy project communicate via service names over the internal Docker Swarm network.

✅ 5. (Optional) Expose Externally for pgAdmin or TablePlus

  1. Open your PostgreSQL service → General tab
  2. Under External Credentials, enter an External Port (e.g. 5433)
  3. Click Save
  4. Open that port in the firewall: 
   sudo firewall-cmd --permanent --add-port=5433/tcp
   sudo firewall-cmd --reload
Enter fullscreen mode Exit fullscreen mode
  1. Connect from your local machine: 
   Host: YOUR_SERVER_IP | Port: 5433
   Database: myapp      | User: myapp_user
   Password: StrongPass@2025
Enter fullscreen mode Exit fullscreen mode

9️⃣ Ninth Step — Set Up Redis for Your App

Dokploy runs its own internal Redis for its deployment queue. The one you create here is completely separate — it is your application's cache/session/queue store.

✅ 1. Add a Redis Service

  1. Inside your project → Create New Service → Database → Redis
  2. Fill in:
Field Example Value
Service Name my-app-cache
Redis Password RedisPass@2025
Redis Version 7
  1. Click Create

✅ 2. Deploy Redis

Go to the General tab → Click Deploy → Wait for Running (green)

✅ 3. Get the Internal Connection Strings 

REDIS_HOST=my-app-cache
REDIS_PORT=6379
REDIS_PASSWORD=RedisPass@2025
REDIS_URL=redis://:RedisPass@2025@my-app-cache:6379
Enter fullscreen mode Exit fullscreen mode

Redis supports database numbers 0–15 for separating use cases:

CACHE_URL=redis://:RedisPass@2025@my-app-cache:6379/0
SESSION_URL=redis://:RedisPass@2025@my-app-cache:6379/1
QUEUE_URL=redis://:RedisPass@2025@my-app-cache:6379/2
Enter fullscreen mode Exit fullscreen mode

✅ 4. (Optional) Expose Externally for RedisInsight

  1. Open your Redis service → General tab
  2. Under External Credentials, enter External Port 6379
  3. Click Save
  4. Open the port: 
   sudo firewall-cmd --permanent --add-port=6379/tcp
   sudo firewall-cmd --reload
Enter fullscreen mode Exit fullscreen mode
  1. In RedisInsight, connect with:
    • Host: YOUR_SERVER_IP | Port: 6379
    • Username: default | Password: RedisPass@2025

🔟 Tenth Step — Deploy Your Application

✅ 1. Add an Application Service

Inside your project → Create New Service → Application

Choose a source:

  • GitHub / GitLab — connects your repo with auto CI/CD on every push
  • Docker Compose — upload your own docker-compose.yml
  • Docker Image — pull from Docker Hub or any registry

✅ 2. Set Environment Variables

In the Environment tab:

DATABASE_URL=postgresql://myapp_user:StrongPass@2025@my-app-db:5432/myapp
REDIS_URL=redis://:RedisPass@2025@my-app-cache:6379
PORT=3333
NODE_ENV=production
Enter fullscreen mode Exit fullscreen mode

Click Save.

✅ 3. Configure a Domain

  1. Domains tab → Add Domain
  2. Enter your app's subdomain (e.g. app.yourdomain.com)
  3. Set Container Port to whatever your app listens on (e.g. 3333)
  4. Select Let's Encrypt → Click Save

Make sure app.yourdomain.com has an A record pointing to your server IP.

✅ 4. Deploy and Verify

General tab → Deploy → Watch the live logs → Visit https://app.yourdomain.com

📝 AlmaLinux Troubleshooting

⭐ SSH Disconnected After firewall-cmd --reload

This means firewalld was not running before you ran the reload, so the command activated the service for the first time and reset the connection. To recover without SSH:

  1. Log in via your VPS provider's web console / VNC (not SSH)
  2. Run: 
   sudo systemctl start firewalld
   sudo firewall-cmd --permanent --add-service=ssh
   sudo firewall-cmd --reload
Enter fullscreen mode Exit fullscreen mode
  1. SSH will now work normally again

⭐ cockpit: command not found Error

This is harmless. It happens when the output of firewall-cmd --list-services (cockpit dhcpv6-client ssh) is accidentally run as a bash command. The output is just showing which services are allowed — it is not something you run. Ignore it.

⭐ Dokploy Installer Fails with "Unsupported distribution"

Docker was not installed before the Dokploy installer ran. Go back to Step 3:

sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

export ADVERTISE_ADDR="YOUR_SERVER_IP"
curl -sSL https://dokploy.com/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

⭐ Swarm Init Fails / Cannot Detect IP

Always export ADVERTISE_ADDR before running the installer:

export ADVERTISE_ADDR="YOUR_SERVER_IP"
curl -sSL https://dokploy.com/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

⭐ Port 3000 Not Accessible 

sudo firewall-cmd --list-ports
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --reload
docker service ls
docker ps | grep dokploy
Enter fullscreen mode Exit fullscreen mode

⭐ SSL Certificate Not Issued 

# Check Traefik logs for Let's Encrypt errors
docker logs $(docker ps -q -f name=dokploy_dokploy-traefik) 2>&1 | tail -50

# Confirm ports 80 and 443 are open
sudo firewall-cmd --list-ports
sudo firewall-cmd --list-services

# Confirm DNS resolves to this server
nslookup yourdomain.com
Enter fullscreen mode Exit fullscreen mode

⭐ App Cannot Reach the Database or Redis

The service name must be used — never localhost:

# WRONG
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
# CORRECT
DATABASE_URL=postgresql://user:pass@my-app-db:5432/mydb
Enter fullscreen mode Exit fullscreen mode

Verify all services share the same network:

docker network inspect dokploy-network
Enter fullscreen mode Exit fullscreen mode

⭐ SELinux Blocking Container Connections 

sudo setsebool -P httpd_can_network_connect 1
# Check what SELinux is denying
sudo ausearch -m avc -ts recent
Enter fullscreen mode Exit fullscreen mode

⭐ Services Do Not Start After Reboot

Both firewalld and docker must be enabled to survive reboots:

sudo systemctl enable firewalld
sudo systemctl enable docker
sudo systemctl status firewalld
sudo systemctl status docker
Enter fullscreen mode Exit fullscreen mode

⭐ Containers Crash with bridge-nf-call-iptables: permission denied (OpenVZ / Shared-Kernel VPS)

Symptom: All Dokploy services crash in a restart loop immediately after installation. Running docker service ps dokploy-postgres --no-trunc shows repeated failures with this error:

"starting container failed: failed to set up container networking: error creating
external connectivity network: open /proc/sys/net/bridge/bridge-nf-call-iptables:
permission denied"
Enter fullscreen mode Exit fullscreen mode

Root cause: Your VPS is running on OpenVZ (or a similar container-based virtualization platform) with a shared kernel. The host provider has restricted access to bridge networking kernel features. No command you run inside your VPS can fully fix this — the kernel is shared with other customers and the provider controls these capabilities at the host level.

You can identify an OpenVZ VPS by running:

systemd-detect-virt
# or
hostnamectl | grep Virtualization
Enter fullscreen mode Exit fullscreen mode

If the output is openvz or lxc, you are on a shared kernel.

Option 1 — Disable Docker's iptables (Try First)

This tells Docker not to use iptables for container networking, which avoids the permission error entirely:

# 1. Stop everything and leave the swarm
docker swarm leave --force

# 2. Remove any leftover Dokploy containers and volumes
docker container prune -f
docker volume prune -f
docker network prune -f

# 3. Configure Docker daemon to skip iptables
cat > /etc/docker/daemon.json << 'EOF'
{
  "iptables": false,
  "ip-masq": false
}
EOF

# 4. Restart Docker
sudo systemctl restart docker
sudo systemctl status docker

# 5. Reinstall Dokploy
export DOCKER_IGNORE_BR_NETFILTER_ERROR=1
export ADVERTISE_ADDR="YOUR_SERVER_IP"
export DOKPLOY_VERSION="v0.28.6"
curl -sSL https://dokploy.com/install.sh | sh
Enter fullscreen mode Exit fullscreen mode

⚠️ Trade-off: Disabling iptables means Docker will not set up NAT rules for containers automatically. Traffic routing between your app containers and the outside world depends entirely on Traefik (which Dokploy includes). For most Dokploy use cases this is fine, but direct port-forwarding from host to container will not work without manual iptables rules.

Option 2 — Contact Your Hosting Provider (Most Reliable)

If Option 1 fails, the only permanent fix is at the host level. Open a support ticket with your provider and include the following:

"I need the following kernel features enabled for my VPS:

  • bridge and br_netfilter kernel modules loaded
  • net.bridge.bridge-nf-call-iptables=1 set on the host node
  • net.bridge.bridge-nf-call-ip6tables=1 set on the host node
  • TUN/TAP device access enabled

I am running Docker Swarm, which requires these. I am currently getting:
open /proc/sys/net/bridge/bridge-nf-call-iptables: permission denied"

💡 Long-term recommendation: If your provider cannot enable these features, consider migrating to a KVM-based VPS (sometimes called "full virtualization" or "dedicated kernel" VPS). KVM gives your VPS its own isolated kernel where you have full control over kernel modules and sysctl settings. OpenVZ/LXC VPS plans are cheaper but impose these kernel-sharing restrictions that are incompatible with Docker Swarm.

⚙️ Managing Dokploy (Both OS) 

# List all Dokploy platform services and their status
docker service ls

# List all running containers
docker ps

# View Dokploy panel logs
docker logs $(docker ps -q -f name=dokploy_dokploy)

# View Traefik logs (SSL and routing issues)
docker logs $(docker ps -q -f name=dokploy_dokploy-traefik)

# Force restart the Dokploy panel
docker service update --force dokploy_dokploy

# Check system resource usage live
docker stats

# Check disk usage
df -h

# Check memory
free -h
Enter fullscreen mode Exit fullscreen mode

Update Dokploy to the Latest Version 

curl -sSL https://dokploy.com/install.sh | sh -s update
Enter fullscreen mode Exit fullscreen mode

🔑 Ubuntu vs AlmaLinux — Key Differences

Area Ubuntu AlmaLinux
Package manager apt dnf
Docker install Auto by Dokploy installer Must install manually first (Step 3)
Docker repository download.docker.com/linux/ubuntu download.docker.com/linux/centos
Firewall tool ufw firewall-cmd (firewalld)
Start firewall ufw enable (starts itself) systemctl enable firewalld && systemctl start firewalld first — then add rules
SSH safety step ufw allow 22/tcp before ufw enable firewall-cmd --permanent --add-service=ssh before --reload
Firewall persistence ufw enable persists rules --permanent flag persists rules
SELinux Inactive by default Active — must run setsebool -P httpd_can_network_connect 1
Service auto-start Services start automatically after install Must run systemctl enable manually
EPEL repo Not needed Required — dnf install epel-release in Step 2
Advertise address Usually auto-detected Must set export ADVERTISE_ADDR manually before installer
Virtualization risk Rare Check for OpenVZ — see bridge-nf-call-iptables troubleshooting

📚 Official References

Top comments (0)