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:

• 🟠 Ubuntu Guide
• 🔵 AlmaLinux Guide

✅ Versions Verified (March 2026)

✅ Minimum Server Requirements

✅ Required Ports

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

🟠 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

✅ 3. Accept the Host Key

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

Type yes and press Enter.

✅ 4. Enter Your Password When Prompted

root@YOUR_SERVER_IP's password:

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

✅ 5. You're In

root@your-hostname:~#

2️⃣ Second Step — Prepare the System

✅ 1. Clear the Terminal

clear

✅ 2. Confirm Your OS

lsb_release -a

Expected:

Distributor ID: Ubuntu
Description:    Ubuntu 22.04.x LTS

✅ 3. Update Package List

sudo apt update

✅ 4. Upgrade All Packages

sudo apt upgrade -y

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

✅ 6. Reboot If a Kernel Update Was Applied

sudo reboot

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

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

✅ 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

✅ 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

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

sudo systemctl enable --now docker

✅ 6. Verify the Installation

docker --version
docker compose version

Expected:

Docker version 29.x.x, build ...
Docker Compose version v5.x.x

✅ 7. Run a Quick Test

docker run hello-world

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

✅ 2. Allow SSH First (Critical Step)

sudo ufw allow 22/tcp

✅ 3. Allow the Remaining Required Ports

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 3000/tcp

✅ 4. Enable the Firewall

sudo ufw enable

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

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

5️⃣ Fifth Step — Install Dokploy

✅ 1. Run the Official Installer

curl -sSL https://dokploy.com/install.sh | sh

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

Wait the full 15 seconds before opening the browser.

✅ 3. Confirm All Services Are Running

docker service ls

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

✅ 4. Confirm the Panel Responds

curl -I http://127.0.0.1:3000/

Expected:

HTTP/1.1 302 Found
Location: /register

6️⃣ Sixth Step — Create Your Admin Account

✅ 1. Open the Panel in Your Browser

http://YOUR_SERVER_IP:3000

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

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

✅ 2. Verify DNS Propagation

nslookup yourdomain.com

Expected:

Name:    yourdomain.com
Address: YOUR_SERVER_IP

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

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

⚠️ 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:

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

⚠️ 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

1. Connect from your local machine:

   Host: YOUR_SERVER_IP | Port: 5433
   Database: myapp      | User: myapp_user
   Password: StrongPass@2025

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:

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

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

✅ 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

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

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

⭐ 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

⭐ 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

Verify all services share the same network:

docker network inspect dokploy-network

⭐ Docker Does Not Start After Reboot

sudo systemctl enable docker
sudo systemctl start docker
sudo systemctl status docker

🔵 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

✅ 3. Accept the Host Key

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

Type yes and press Enter.

✅ 4. Enter Your Password When Prompted

root@YOUR_SERVER_IP's password:

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

✅ 5. You're In

[root@your-hostname ~]#

2️⃣ Second Step — Prepare the System

✅ 1. Clear the Terminal

clear

✅ 2. Confirm Your OS

cat /etc/os-release

Expected:

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

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

sudo dnf install -y epel-release

✅ 4. Check for Available Updates

sudo dnf check-update

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

✅ 5. Apply All Updates

sudo dnf upgrade -y

✅ 6. Install Essential Tools

sudo dnf install -y curl wget ca-certificates dnf-plugins-core

✅ 7. Reboot If a Kernel Update Was Applied

sudo reboot

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

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

✅ 3. Install Docker Engine and Compose Plugin

sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

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

✅ 5. Verify the Installation

docker --version
docker compose version

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

Docker version 29.3.0, build ...
Docker Compose version v5.1.0

✅ 6. Run a Quick Test

docker run hello-world

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

✅ 2. Confirm firewalld Is Active

sudo systemctl status firewalld

Look for Active: active (running):

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

✅ 3. Check What the Default Zone Already Allows

sudo firewall-cmd --list-all

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

services: cockpit dhcpv6-client ssh

⚠️ 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

✅ 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

✅ 6. Reload firewalld to Enforce All Rules

sudo firewall-cmd --reload

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

Expected ports:

80/tcp 443/tcp 3000/tcp

Expected services (SSH must be listed):

cockpit dhcpv6-client ssh

✅ 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

Confirm it is set:

getsebool httpd_can_network_connect

Expected:

httpd_can_network_connect --> on

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"

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"

Skip this to get the latest stable version automatically.

✅ 3. Run the Official Dokploy Installer

curl -sSL https://dokploy.com/install.sh | sh

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

Wait the full 15 seconds before opening the browser.

✅ 5. Confirm All Services Are Running

docker service ls

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

✅ 6. Confirm the Panel Responds

curl -I http://127.0.0.1:3000/

Expected:

HTTP/1.1 302 Found
Location: /register

6️⃣ Sixth Step — Create Your Admin Account

✅ 1. Open the Panel in Your Browser

http://YOUR_SERVER_IP:3000

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

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

✅ 2. Verify DNS Propagation

nslookup yourdomain.com

Expected:

Name:    yourdomain.com
Address: YOUR_SERVER_IP

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

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

⚠️ 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:

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

⚠️ 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

1. Connect from your local machine:

   Host: YOUR_SERVER_IP | Port: 5433
   Database: myapp      | User: myapp_user
   Password: StrongPass@2025

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:

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

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

✅ 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

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

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

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

⭐ 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

⭐ 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

⭐ 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

⭐ 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

Verify all services share the same network:

docker network inspect dokploy-network

⭐ SELinux Blocking Container Connections

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

⭐ 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

⭐ 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"

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

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

⚠️ 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

Update Dokploy to the Latest Version

curl -sSL https://dokploy.com/install.sh | sh -s update

🔑 Ubuntu vs AlmaLinux — Key Differences

📚 Official References

• Dokploy Installation Docs
• Dokploy Database Docs
• Dokploy Database Connection Docs
• Dokploy Domains & SSL Docs
• Dokploy GitHub
• Docker for Ubuntu
• Docker for CentOS/RHEL (used for AlmaLinux)
• Verified AlmaLinux + Dokploy setup — Shape.Host (March 2026)