Dokploy Setup Guide

Dokploy is a free, self-hosted PaaS that bundles Docker Swarm, Traefik, PostgreSQL, and Redis into a single web dashboard, allowing users to deploy apps, manage databases, and handle domains without manual Docker configuration. The setup guide walks through provisioning a VPS with at least 2 GB RAM and 2 vCPU, connecting via SSH, updating the OS, installing Docker, and configuring the firewall to open ports 22, 80, 443, and 3000.

What is Dokploy? Dokploy is a free, self-hosted PaaS — your own Vercel/Heroku that runs on your VPS. It bundles Docker Swarm, Traefik for SSL + routing , PostgreSQL, and Redis into one web dashboard. You deploy apps, manage databases, and handle domains all from a single UI — no manual Docker config needed. | Resource | Minimum | |---|---| | RAM | 2 GB 4 GB recommended | | CPU | 2 vCPU | | Disk | 30 GB 50 GB recommended | | Port | Purpose | |---|---| 80 | HTTP traffic Traefik | 443 | HTTPS traffic Traefik | 3000 | Dokploy web UI | ✅ 1. Get Your Credentials You'll need these three things from your hosting provider: 568.82.48.166 root Subham@Xam 08 ✅ 2. Connect via Terminal ssh root@568.82.48.166 ✅ 3. Verify the Connection You'll see a host authenticity prompt: The authenticity of host '568.82.48.166' can't be established. Are you sure you want to continue connecting yes/no/ fingerprint ? Type yes and press Enter. ✅ 4. Enter Your Password root@568.82.48.166's password: Paste your password and press Enter. The terminal won't show characters while typing — that's normal. ✅ 5. Success You'll see the Ubuntu welcome screen and land in the shell: root@your-hostname:~ ✅ 1. Clear the Terminal clear ✅ 2. Verify Your OS lsb release -a Expected output: Distributor ID: Ubuntu Description: Ubuntu 22.04.x LTS Release: 22.04 ✅ 3. Update the Package List sudo apt update ✅ 4. Upgrade Installed Packages sudo apt upgrade -y If you see configuration prompts during upgrade, press Tab to highlight OK and press Enter . ✅ 5. Install Essential Tools sudo apt install -y curl wget ca-certificates ✅ 6. Reboot if Prompted If the upgrade mentions a kernel update: sudo reboot Then SSH back in. On Ubuntu, Dokploy's installer can auto-install Docker. However, it's best practice to install Docker yourself first so you have full control over the version and configuration. ✅ 1. Remove Any Old Docker Versions sudo apt remove -y docker docker-engine docker.io containerd runc It's fine if these aren't installed — the command will just say "not installed". ✅ 2. Add Docker's Official GPG Key and Repository 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 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 ✅ 3. Install Docker Engine + Compose sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin ✅ 4. Enable and Start Docker sudo systemctl enable --now docker ✅ 5. Verify Docker Installation docker --version docker compose version Expected output: Docker version 29.x.x, build ... Docker Compose version v5.x.x ✅ 6. Test Docker Works docker run hello-world You should see Hello from Docker in the output. ✅ 1. Check Firewall Status sudo ufw status ✅ 2. Open Required Ports SSH important — don't lock yourself out sudo ufw allow 22/tcp HTTP sudo ufw allow 80/tcp HTTPS sudo ufw allow 443/tcp Dokploy Web UI sudo ufw allow 3000/tcp Enable the firewall sudo ufw enable ✅ 3. Verify Rules sudo ufw status numbered Expected output: 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 ✅ 1. Run the Dokploy Installer curl -sSL https://dokploy.com/install.sh | sh The installer will automatically: dokploy-network overlay network dokploy-postgres dokploy-redis dokploy-traefik ✅ 2. Wait for the Installer to Finish You'll see: Congratulations, Dokploy is installed Wait 15 seconds for the server to start Please go to http://568.82.48.166:3000 Wait the full 15 seconds before opening the browser. ✅ 3. Verify All Platform Services Are Running docker service ls Expected output — all services should 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 Also confirm running containers: docker ps --format '{{.Names}}\t{{.Image}}\t{{.Status}}' ✅ 4. Confirm the Panel is Responding curl -I http://127.0.0.1:3000/ Expected: HTTP/1.1 302 Found Location: /register ✅ 1. Open Dokploy in Your Browser http://568.82.48.166:3000 You'll be redirected to the registration page. ✅ 2. Create Your Admin Account Fill in: Click Create Account . ✅ 3. You're In the Dashboard The main sections you'll use: Purchase from GoDaddy, Namecheap, Cloudflare, etc. In your domain provider's DNS management, add: | Type | Name | Points To | TTL | |---|---|---|---| A | @ | 568.82.48.166 | 1 hour | A | www | 568.82.48.166 | 1 hour | For a panel subdomain e.g., panel.xyz.com : | Type | Name | Points To | TTL | |---|---|---|---| A | panel | 568.82.48.166 | 1 hour | nslookup yourdomain.com Expected: Name: yourdomain.com Address: 568.82.48.166 DNS can take up to 24 hoursto propagate globally. Usually 5–30 minutes. yourdomain.com Dokploy's built-in Traefik will automatically issue and renew the SSL certificate. https://yourdomain.com You should see the Dokploy login page with a padlock in the browser. Once your domain + HTTPS is confirmed working, remove port 3000 exposure: docker service update --publish-rm "published=3000,target=3000,mode=host" dokploy ⚠️ Only run this AFTER verifying your domain works. Otherwise you'll lose access. Note:Dokploy already has its own internal PostgreSQL running for its own data. The one you create here is aseparate database for your application. my-app | Field | Example | |---|---| | Service Name | my-app-db | | Database Name | myapp | | Database User | myapp user | | Database Password | StrongPass@2025 | | PostgreSQL Version | 16 | For app containers in the same project , use the service name as hostname: 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 my-app-db the service name as the host —NOT localhost or the server IP. Containers in the same project communicate by service name over the internal Docker network. To connect from your local machine using pgAdmin or TablePlus: 5433 sudo ufw allow 5433/tcp Host: 568.82.48.166 Port: 5433 Database: myapp User: myapp user Password: StrongPass@2025 Note:Dokploy has its own internal Redis for deployment queuing. The one you create here is aseparate Redis for your application caching, sessions, queues . | Field | Example | |---|---| | Service Name | my-app-cache | | Redis Password | RedisPass@2025 | | Redis Version | 7 | REDIS HOST=my-app-cache REDIS PORT=6379 REDIS PASSWORD=RedisPass@2025 REDIS URL=redis://:RedisPass@2025@my-app-cache:6379 For multiple use cases using Redis database numbers 0–15 : Caching DB 0 CACHE URL=redis://:RedisPass@2025@my-app-cache:6379/0 Sessions DB 1 SESSION URL=redis://:RedisPass@2025@my-app-cache:6379/1 Job Queues DB 2 QUEUE URL=redis://:RedisPass@2025@my-app-cache:6379/2 To manage Redis from your local RedisInsight https://redis.com/redis-enterprise/redis-insight/ : 6379 sudo ufw allow 6379/tcp 568.82.48.166 6379 default RedisPass@2025 docker-compose.yml Go to the Environment tab and add your variables: 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 . app.yourdomain.com 3333 Make sure app.yourdomain.com has an A record pointing to your server IP in your DNS settings. https://app.yourdomain.com View all Dokploy platform services docker service ls View all running containers docker ps Check Dokploy panel logs docker logs $ docker ps -q -f name=dokploy dokploy Check Traefik logs for SSL/routing issues docker logs $ docker ps -q -f name=dokploy dokploy-traefik Restart the Dokploy panel docker service update --force dokploy dokploy Check system resources docker stats df -h free -h curl -sSL https://dokploy.com/install.sh | sh -s update Check firewall rules sudo ufw status Open port if missing sudo ufw allow 3000/tcp Verify Dokploy is running docker service ls docker ps | grep dokploy Check Traefik logs for ACME errors docker logs $ docker ps -q -f name=dokploy dokploy-traefik 2 &1 | tail -50 Ensure ports 80 and 443 are open sudo ufw allow 80/tcp sudo ufw allow 443/tcp Verify DNS resolves correctly nslookup yourdomain.com Use the service name not localhost as the hostname: WRONG DATABASE URL=postgresql://user:pass@localhost:5432/mydb CORRECT DATABASE URL=postgresql://user:pass@my-app-db:5432/mydb Verify all services are on the same network: docker network inspect dokploy-network Make sure Docker starts on boot sudo systemctl enable docker sudo systemctl status docker ========================================================= What is Dokploy? Dokploy is a free, self-hosted PaaS — your own Vercel/Heroku that runs on your VPS. It bundles Docker Swarm, Traefik for SSL + routing , PostgreSQL, and Redis into one web dashboard. You deploy apps, manage databases, and handle domains all from a single UI — no manual Docker config needed.⚠️ AlmaLinux Critical Warning:Dokploy's default installer falls back to Docker's convenience script whichdoes NOT support AlmaLinuxand fails with Unsupported distribution 'almalinux' . Youmust install Docker manually firstfrom Docker's official CentOS repository before running the Dokploy installer.Step 3 covers this in full. | Resource | Minimum | |---|---| | RAM | 2 GB 4 GB recommended | | CPU | 2 vCPU | | Disk | 30 GB 50 GB recommended | | Port | Purpose | |---|---| 80 | HTTP traffic Traefik | 443 | HTTPS traffic Traefik | 3000 | Dokploy web UI | ✅ 1. Get Your Credentials You'll need these three things from your hosting provider: 568.82.48.166 root Subham@Xam 08 ✅ 2. Connect via Terminal ssh root@568.82.48.166 ✅ 3. Verify the Connection You'll see a host authenticity prompt: The authenticity of host '568.82.48.166' can't be established. Are you sure you want to continue connecting yes/no/ fingerprint ? Type yes and press Enter. ✅ 4. Enter Your Password root@568.82.48.166's password: Paste your password and press Enter. The terminal won't show characters while typing — that's normal. ✅ 5. Success You'll land in the AlmaLinux shell: root@your-hostname ~ ✅ 1. Clear the Terminal clear ✅ 2. Verify Your OS Confirm you're running AlmaLinux: cat /etc/os-release Expected output: NAME="AlmaLinux" VERSION="9.x Seafoam Ocelot " ID="almalinux" ID LIKE="rhel centos fedora" ... ✅ 3. Enable EPEL Repository EPEL Extra Packages for Enterprise Linux is required for many packages on AlmaLinux: sudo dnf install -y epel-release ✅ 4. Update the Package List sudo dnf check-update Exit code 100 is normal — it just means updates are available. ✅ 5. Upgrade Installed Packages sudo dnf upgrade -y ✅ 6. Install Essential Tools sudo dnf install -y curl wget ca-certificates dnf-plugins-core ✅ 7. Reboot if Prompted If the upgrade includes a kernel update: sudo reboot Then SSH back in. ⚠️ This step is required and unique to AlmaLinux.Dokploy's built-in Docker installer does NOT support AlmaLinux. When it tries, it uses Docker's convenience script which returns: ERROR: Unsupported distribution 'almalinux' and the entire Dokploy installation fails. The fix is to install Docker yourself first from Docker's official CentOSrepository — which AlmaLinux is fully binary-compatible with. Do not skip this 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 It's fine if these aren't installed — the command will just skip them. ✅ 2. Add Docker's Official Repository for CentOS/RHEL AlmaLinux is binary-compatible with RHEL/CentOS, so use Docker's CentOS repo: sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo ✅ 3. Install Docker Engine + Compose Plugin sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin When prompted to accept the GPG key, type y and press Enter. ✅ 4. Enable and Start Docker On AlmaLinux, services don't auto-start — you must enable them explicitly: sudo systemctl enable --now docker ✅ 5. Verify Docker Installation docker --version docker compose version Expected output: Docker version 29.x.x, build ... Docker Compose version v5.x.x ✅ 6. Test Docker Works docker run hello-world You should see Hello from Docker in the output. ✅ Docker is now installed. The Dokploy installer will detect it and skip its own Docker installation step — allowing it to run successfully on AlmaLinux. AlmaLinux uses firewalld— not ufw or raw iptables . All firewall management is done with firewall-cmd . ✅ 1. Check Firewall Status sudo firewall-cmd --state ✅ 2. Open Required Ports SSH ensure you don't lose access sudo firewall-cmd --permanent --add-port=22/tcp HTTP sudo firewall-cmd --permanent --add-port=80/tcp HTTPS sudo firewall-cmd --permanent --add-port=443/tcp Dokploy Web UI sudo firewall-cmd --permanent --add-port=3000/tcp Apply all changes sudo firewall-cmd --reload ✅ 3. Verify Open Ports sudo firewall-cmd --list-ports Expected output: 22/tcp 80/tcp 443/tcp 3000/tcp ✅ 4. Fix SELinux for Network Proxying AlmaLinux Specific AlmaLinux enables SELinux by default, which can block containers from making network connections. Allow it: sudo setsebool -P httpd can network connect 1 Why firewall-cmd?Unlike Ubuntu's ufw , AlmaLinux uses firewalld. The --permanent flag makes rules survive reboots automatically — no extra package like netfilter-persistent is needed. ✅ 1. Set Your Server's Public IP as the Advertise Address The Dokploy installer sometimes cannot auto-detect the IP on AlmaLinux. Always set it manually: export ADVERTISE ADDR="568.82.48.166" Replace 568.82.48.166 with your actual VPS IP address. ✅ 2. Run the Dokploy Installer curl -sSL https://dokploy.com/install.sh | sh Because Docker is already installed Step 3 , the installer will skip Docker setup and go straight to deploying Dokploy's services: dokploy dokploy-postgres dokploy-redis dokploy-traefik ✅ 3. Wait for Services to Start You'll see: Congratulations, Dokploy is installed Wait 15 seconds for the server to start Please go to http://568.82.48.166:3000 Wait the full 15 seconds before opening the browser. ✅ 4. Verify All Platform Services Are Running docker service ls Expected output — all services should 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 Also confirm containers are running: docker ps --format '{{.Names}}\t{{.Image}}\t{{.Status}}' ✅ 5. Confirm the Panel is Responding curl -I http://127.0.0.1:3000/ Expected: HTTP/1.1 302 Found Location: /register ✅ 1. Open Dokploy in Your Browser http://568.82.48.166:3000 You'll be redirected to the registration page. ✅ 2. Create Your Admin Account Fill in: Click Create Account . ✅ 3. You're In the Dashboard The main sections you'll use: Purchase from GoDaddy, Namecheap, Cloudflare, etc. In your domain provider's DNS management, add: | Type | Name | Points To | TTL | |---|---|---|---| A | @ | 568.82.48.166 | 1 hour | A | www | 568.82.48.166 | 1 hour | For a panel subdomain e.g., panel.xyz.com : | Type | Name | Points To | TTL | |---|---|---|---| A | panel | 568.82.48.166 | 1 hour | nslookup yourdomain.com Expected: Name: yourdomain.com Address: 568.82.48.166 DNS can take up to 24 hoursto propagate globally. Usually 5–30 minutes. yourdomain.com Dokploy's built-in Traefik automatically issues and renews the SSL certificate via Let's Encrypt. https://yourdomain.com You should see the Dokploy login page with a padlock icon in the browser. Once your domain + HTTPS is confirmed working, remove port 3000 exposure: docker service update --publish-rm "published=3000,target=3000,mode=host" dokploy ⚠️ Only run this AFTER verifying your domain works. Otherwise you'll lose access to the panel. Note:Dokploy already has itsown internal PostgreSQLrunning for its own data. The database you create here is aseparate, isolated PostgreSQL instance for your application. my-app | Field | Example | |---|---| | Service Name | my-app-db | | Database Name | myapp | | Database User | myapp user | | Database Password | StrongPass@2025 | | PostgreSQL Version | 16 | For app containers in the same project , use the service name as the hostname: 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 my-app-db the service name you set as the host —NOT localhost or the server IP. Containers in the same Dokploy project communicate with each other by service name over the internal Docker network. To connect from your local machine using pgAdmin or TablePlus: 5433 sudo firewall-cmd --permanent --add-port=5433/tcp sudo firewall-cmd --reload Host: 568.82.48.166 Port: 5433 Database: myapp User: myapp user Password: StrongPass@2025 Note:Dokploy has itsown internal Redisfor managing deployment queues. The one you create here is aseparate Redis instance for your application— caching, sessions, job queues, etc. | Field | Example | |---|---| | Service Name | my-app-cache | | Redis Password | RedisPass@2025 | | Redis Version | 7 | REDIS HOST=my-app-cache REDIS PORT=6379 REDIS PASSWORD=RedisPass@2025 REDIS URL=redis://:RedisPass@2025@my-app-cache:6379 For multiple use cases using Redis database numbers 0–15 : Caching DB 0 CACHE URL=redis://:RedisPass@2025@my-app-cache:6379/0 Sessions DB 1 SESSION URL=redis://:RedisPass@2025@my-app-cache:6379/1 Job Queues DB 2 QUEUE URL=redis://:RedisPass@2025@my-app-cache:6379/2 To manage Redis from your local RedisInsight https://redis.com/redis-enterprise/redis-insight/ : 6379 sudo firewall-cmd --permanent --add-port=6379/tcp sudo firewall-cmd --reload 568.82.48.166 6379 default RedisPass@2025 docker-compose.yml Go to the Environment tab and add your variables: 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 . app.yourdomain.com 3333 Make sure app.yourdomain.com also has an A record pointing to your server IP. https://app.yourdomain.com View all Dokploy platform services docker service ls View all running containers docker ps Check Dokploy panel logs docker logs $ docker ps -q -f name=dokploy dokploy Check Traefik logs for SSL/routing issues docker logs $ docker ps -q -f name=dokploy dokploy-traefik Restart the Dokploy panel docker service update --force dokploy dokploy Check system resources docker stats df -h free -h curl -sSL https://dokploy.com/install.sh | sh -s update This means Docker was not pre-installed. Go back to Step 3 and install Docker manually first: 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 Then re-run Dokploy installer with your IP export ADVERTISE ADDR="568.82.48.166" curl -sSL https://dokploy.com/install.sh | sh Always export ADVERTISE ADDR before the installer on AlmaLinux: export ADVERTISE ADDR="YOUR PUBLIC IP" curl -sSL https://dokploy.com/install.sh | sh Check open ports sudo firewall-cmd --list-ports Add port if missing sudo firewall-cmd --permanent --add-port=3000/tcp sudo firewall-cmd --reload Verify Dokploy is actually running docker service ls docker ps | grep dokploy Check Traefik logs for ACME/Let's Encrypt errors docker logs $ docker ps -q -f name=dokploy dokploy-traefik 2 &1 | tail -50 Ensure HTTP and HTTPS ports are open sudo firewall-cmd --permanent --add-service=http sudo firewall-cmd --permanent --add-service=https sudo firewall-cmd --reload Verify domain points to your server nslookup yourdomain.com Use the service name not localhost as the hostname in your env vars: WRONG DATABASE URL=postgresql://user:pass@localhost:5432/mydb CORRECT use your Dokploy service name DATABASE URL=postgresql://user:pass@my-app-db:5432/mydb Verify services are on the same Docker network: docker network inspect dokploy-network Allow proxy network connections sudo setsebool -P httpd can network connect 1 Check recent SELinux denials sudo ausearch -m avc -ts recent Ensure Docker starts on boot required on AlmaLinux sudo systemctl enable docker sudo systemctl status docker | Task | Command | |---|---| | View all Dokploy services | docker service ls | | View running containers | docker ps | | Check Dokploy panel logs | docker logs $ docker ps -q -f name=dokploy dokploy | | Update Dokploy | curl -sSL | sudo firewall-cmd --permanent --add-port=PORT/tcp && sudo firewall-cmd --reload sudo firewall-cmd --list-ports sudo setsebool -P httpd can network connect 1 docker service update --force SERVICE NAME | Area | Ubuntu | AlmaLinux | |---|---|---| | Docker installation | Auto-handled by Dokploy installer | Must be done manually first Step 3 | | Docker repo | download.docker.com/linux/ubuntu | download.docker.com/linux/centos | | Package manager | apt | dnf | | Firewall tool | ufw | firewall-cmd firewalld | | Firewall persistence | ufw enable | Built-in with --permanent flag | | SELinux | Not active by default | Active — need setsebool -P httpd can network connect 1 | | Service boot enable | Usually automatic | Must run systemctl enable manually | | EPEL repo | Not needed | Required dnf install epel-release |