Agentic AI

Dokploy – A Beginner’s Guide to Easy Web App Deployment

Written by

anders@pier.dk

in





Research Response

Dokploy – Deploy Your Web Apps the Easy Way

(An in‑depth guide for beginners and seasoned devs alike)

Table of Contents

  1. What is Dokploy?
  2. Why Use Dokploy?
  3. Prerequisites
  4. Installation Methods
  5. Getting Started After Installation
  6. Common Troubleshooting
  7. Security & Maintenance Tips
  8. Resources & Further Reading

What is Dokploy?

Dokploy is a free, open‑source, self‑hosted deployment platform that brings the power of Git‑based continuous deployment to your server with minimal setup. Think of it as a lightweight alternative to services like Vercel, Netlify, or Fly.io – but you control the infrastructure.

Key Features:

Feature Description
Git‑based CI/CD Deploy from GitHub, GitLab, Bitbucket or local repos
Zero‑config builds Auto‑detect the language/framework (Node, Python, Go, PHP, Ruby, Docker, etc.)
Docker‑first All services run in Docker containers; no need to install runtimes yourself
Simple UI Web dashboard for creating apps, managing domains, and inspecting logs
Automatic SSL Lets‑Encrypt certificates for every domain
Database support PostgreSQL, MySQL, MongoDB, Redis – auto‑instantiation via Docker
Webhook & GitHub Actions Trigger deployments from CI pipelines or push events
Self‑hosted Run on your VPS, bare metal, or even Raspberry Pi

Why Use Dokploy?

  • Speed & Simplicity – One command to spin up a production‑ready environment.
  • Control – You own the server, the data, and the secrets.
  • Cost‑Effective – Only pay for the server you already have.
  • Extensibility – Add custom scripts, environment variables, or run side‑by‑side services.
  • Open‑Source – No lock‑in, you can tweak the source code as needed.

If you’re building a personal website, a small SaaS, or a micro‑service stack, Dokploy is an excellent “deploy‑now” solution.

Prerequisites

Requirement Why How to Install
Linux Server (Ubuntu 20.04/22.04+, Debian 11+, or other modern distro) Dokploy runs natively on Linux. Use your provider’s control panel or SSH.
Docker & Docker‑Compose Dokploy itself runs inside Docker containers. sudo apt-get install -y docker.io docker-compose
Sudo/Root Access Installation requires privileged operations. Use sudo or switch to root with sudo -i.
Domain name (optional, but recommended) Lets‑Encrypt requires a domain for SSL. Purchase through any registrar, point A record to your server.
Firewall rules Expose HTTP (80), HTTPS (443), and the Dokploy UI port (8000 by default). sudo ufw allow 80,443,8000

Tip: If you’re on a VPS (DigitalOcean, Hetzner, Linode, etc.), these packages are pre‑installed or easy to add.

Installation Methods

Dokploy offers two main installation paths:

  1. Docker‑Based – Recommended for most users.
  2. Native (Non‑Docker) – For those who want everything inside Docker but prefer not to run Docker as a daemon.

Below we’ll walk through the Docker approach first because it’s the simplest and most reliable.

4.1 Docker‑Based Installation (Recommended)

Step 1 – Install Docker & Docker‑Compose

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io docker-compose
sudo systemctl enable --now docker

Verify:

docker --version
docker compose version

Step 2 – Create a Dedicated User (Optional but Clean)

sudo adduser dokploy
sudo usermod -aG docker dokploy   # Give Docker permissions

Log in as dokploy:

su - dokploy

Step 3 – Pull & Run Dokploy

# Pull latest Dokploy image
docker pull dokploy/dokploy:latest

# Create a persistent data directory
mkdir -p ~/dokploy/data

# Run Dokploy container
docker run -d \
  --name dokploy \
  -p 8000:8000 \
  -v ~/dokploy/data:/app/data \
  --restart unless-stopped \
  dokploy/dokploy:latest

Why /app/data?
Dokploy stores database, config files, and uploaded SSL certs here. Keeping it outside the container ensures persistence across restarts.

Step 4 – Verify

Open your browser and navigate to http://your-server-ip:8000.
You should see Dokploy’s welcome screen.

If you have a domain, point it to your server’s IP, and open http://your-domain.com:8000.

Step 5 – Secure the UI (Optional but Recommended)

  • Basic Auth – Add a .htpasswd file and map the volume into the container.
  • Reverse Proxy – Deploy Nginx or Traefik to expose Dokploy on port 80/443 and enforce HTTPS.

Example Nginx snippet:

server {
    listen 80;
    server_name dokploy.yourdomain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Reload Nginx: sudo systemctl reload nginx

4.2 Native (Non‑Docker) Installation

If you prefer not to use Docker at all (e.g., you have a dedicated environment), you can run Dokploy directly via its Go binary.

  1. Download the Binary
wget https://github.com/dokploy/dokploy/releases/latest/download/dokploy_$(uname -s)_$(uname -m).tar.gz
tar -xzf dokploy_*.tar.gz
sudo mv dokploy /usr/local/bin/
  1. Create Data Directory
sudo mkdir -p /var/lib/dokploy
sudo chown $USER:$USER /var/lib/dokploy
  1. Run Dokploy
dokploy serve --data-dir /var/lib/dokploy
  1. Optional Systemd Service

Create /etc/systemd/system/dokploy.service:

[Unit]
Description=Dokploy Deployment Platform
After=network.target

[Service]
User=dokploy
ExecStart=/usr/local/bin/dokploy serve --data-dir /var/lib/dokploy
Restart=on-failure
WorkingDirectory=/var/lib/dokploy

[Install]
WantedBy=multi-user.target

Enable & start:

sudo systemctl enable --now dokploy

4.3 Deploying via Dokploy’s Self‑Hosting UI

Dokploy offers a Self‑Hosting button in its UI that will deploy an instance of Dokploy on your own server using Docker Compose. This is a great way to automate the entire process:

  1. In the Dokploy UI, click “Self‑Hosting”.
  2. Follow the on‑screen instructions – you’ll provide your server’s IP, SSH credentials, and domain.
  3. The wizard will run a one‑off SSH command that pulls the necessary Docker images and configures everything.

Note: This method is only available on the public Dokploy instance; if you’re running your own local Dokploy, skip this step.

Getting Started After Installation

Once you’ve verified the UI, follow these quick steps to deploy your first app:

  1. Create an App

    • Click “Add App” → choose “New Git App”.
    • Enter a name (e.g., my-site).
    • Add the Git repository URL (public or private; for private, you’ll need to provide SSH keys).

  2. Configure Environment

    • Add environment variables under the Environment tab (e.g., NODE_ENV=production).
    • Set the Build Command and Start Command if Dokploy can’t auto‑detect them.
      Example:

      • Build: npm ci && npm run build
      • Start: npm run start

  3. Add a Database

    • Click “Databases” → Add Database → choose type (PostgreSQL, MySQL, MongoDB, Redis).
    • Dokploy will spin up a Docker container and provide connection details.

  4. Assign a Domain

    • Go to the Domain tab → add your domain.
    • DNS A‑record should point to your server’s IP.
    • Dokploy will request a Lets‑Encrypt cert automatically.

  5. Deploy

    • Click “Deploy Now”.
    • Watch the logs in real‑time; Dokploy will install dependencies, build, and launch the app.

  6. Test

    • Visit https://your-domain.com – you should see your app live!

Common Troubleshooting

Symptom Likely Cause Fix
Docker container fails to start Insufficient memory or wrong port mapping Allocate more RAM (≥512 MB) or change -p 8000:8000
HTTPS certificate not issued DNS not propagated or port 80 blocked Wait for DNS to propagate; open port 80; check firewall
Build fails on a framework Missing build command Manually set Build Command in the UI
Database not reachable Network isolation between containers Ensure network_mode: bridge or --link if using native installation
Logs show “Cannot resolve host” Wrong git URL or missing SSH key Verify repository URL; add SSH key in the Dokploy UI under Git

Security & Maintenance Tips

Topic Recommendation
Firewall Only open 80, 443, and 8000 (or your custom UI port). Use ufw or firewalld.
Updates docker pull dokploy/dokploy:latest and docker restart dokploy every month.
Backups Persist ~/dokploy/data to a backup location; schedule regular snapshots.
Secrets Store secrets in Dokploy’s environment variables; never commit them to Git.
Monitoring Use Grafana + Prometheus (Docker Compose) or simple docker stats to track CPU/memory.
HTTPS Dokploy handles renewals automatically. Verify renewals with sudo certbot renew --dry-run.
User Permissions Run Dokploy as a non‑root user; restrict SSH access.

Resources & Further Reading

  • Official Docs – https://dokploy.com/docs
  • GitHub Repository – https://github.com/dokploy/dokploy
  • Community Forum – https://github.com/dokploy/dokploy/discussions
  • Docker Compose Template – docker-compose.yml in the repo’s root.
  • Tutorials – Search for “Dokploy tutorial” on YouTube or Medium for real‑world examples.

Final Thought

Dokploy gives you the best of both worlds: zero‑config, Git‑driven deployment on your own infrastructure. By following the steps above, you’ll have a self‑hosted CI/CD pipeline up and running in minutes, ready to scale from a personal blog to a full‑stack SaaS.

Happy deploying! 🚀


More posts