TL;DR: Consolidate your projects and streamline deployments with Dokploy, a powerful self-hosting platform. This guide covers setting up Dokploy on multiple VPS servers, deploying a private Docker registry, configuring HTTPS with Let's Encrypt, and managing ports for secure access. With Dokploy, you can automate deployments, link your GitHub account for seamless updates, and host anything from personal projects to production-ready services.

As a freelance developer, I juggled hosting for different client projects across many cheap or even free VPS servers. It was a real headache, I always wanted to streamline this process, but never quite had the motivation to make the switch.

Last month, I got an amazing deal on my VPS hosting service: buy one, get one free! These servers had decent specs, with enough vCPU and RAM to handle all my client projects comfortably. I decided to consolidate all my projects into these two machines, and I needed a tool to simplify the deployment process which, led me to discover Dokploy.

Instead of struggling with individual setups, I could consolidate everything onto these two, letting Dokploy automate deployments, manage HTTPS, and handle security. It's been a game-changer – I've saved time, money, and a lot of headaches.

What is Dokploy

Dokploy is a developer-centric platform for deploying and managing applications across multiple servers. It supports various deployment methods (Nixpacks, Heroku Buildpacks, Dockerfiles, Docker Compose) and offers features like user management, database management, real-time monitoring and more. With a focus on flexibility and open-source principles, Dokploy empowers you to streamline deployments, scale applications, and maintain control of your infrastructure.

Prerequisites

Your VPS server(s)

Specs

To ensure a smooth experience with Dokploy, your server should have at least 2GB of RAM and 30GB of disk space. This specification helps to handle the resources consumed by Docker during builds and prevents system freezes.

If you don't know which provider to choose, Dokploy have some recommendations for you (which will also support them).

Operating system

Dokploy can be run on multiple Linux distros, I usually just use Ubuntu 24.04 LTS for consistency.

Network

To enable HTTPS support for your services, you’ll need a domain name or subdomain that points to your server’s IP address. This is essential for generating SSL/TLS certificates through providers like Let's Encrypt. Ensure your DNS records are correctly configured to map the domain or subdomain to your master server's IP address.

To ensure proper access to your services, configure your firewall or provider’s security group to allow public access to essential ports. Open port 22 for SSH to manage your server, 3000 for the Dokploy dashboard (this can be closed after setting up HTTPS), 443 for secure HTTPS access to your services, and 2377 for Docker Swarm communication. Properly managing these ports enhances connectivity while maintaining security.

Installation

Run the following command (origin) to automatically deploy Dokploy on your master server. This script automatically installs everything required to run Dokploy, including Docker, and starts Dokploy.

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

After completing, navigate to http://<your-server-ip>:3000 to access the dashboard, create an Admin account, and you can start hosting your project.

Deploy your first project!

I will deploy a private docker registry as an example, and it can also be used to connect other machines to your Dokploy instance.

Create a new project

Go to the Projects tab and click Create Project to create a new project, name it registry, fill out some description, and then Create.

You will see your newly created project in the dashboard, now click on it.

Create a new service using a docker image

Currently, it has no services running, click on Create Service/Application to deploy a docker container. Name it docker and select Create. Now go to that service to configure it.

I originally followed this guide on how to deploy a private docker registry

At the Provider section, select Docker and fill out the Docker image registry:2, we will be using the official docker registry image hosted on Docker Hub (registry.hub.docker.com). Process to fill out the Username and Password, you might want to use a personal access token (PAT) instead of your password, then hit Save.

Attach a volume

Go to the Advanced tab, at the Volumes section, and choose Add Volume. We will choose Volume Mount with the Volume Name data and Mount Path /data.

Head over to the Environment tab, click the button to reveal the environment variables, and add our only environment variable:

.envCopy
REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/data

Security

You don't want anyone to access your private registry, so we will add basic auth to our registry.

Go to the Advanced tab again, head to the Security section, click Add Security, fill out your username and password, and then Create.

Configure HTTPS

This step is important, as it will allow you to access your registry from outside your server.

Head to the Domains tab, click Add Domain and fill out the domain that you have prepared. Fill out the Container Port with 5000, toggle HTTPS to On, select Let's Encrypt as your certificate provider, and finally Create.

Finally!

Head to the General tab and click Deploy. You will be taken to the Deployments tab, where you can see the status of your deployment.

Once it's done, you can visit https://<your-registry-domain>/v2/ and log in, if you see the response {} then your registry is up and running!

Add the worker machine

Add the registry

Now that your registry is up, you can head to Dokploy's Registry tab and add your own registry. This is compulsory to add the second machine, as Dokploy will use this registry to deploy your services on other nodes.

Prepare the second machine

On the second machine, install Docker.

shCopy
# Uninstall all conflicting packages
for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get
remove $pkg; done

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc]
https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Actually install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Go back to the master machine, and get the Docker Swarm join token as a worker:

shCopy
sudo docker swarm join-token worker

You will see a command to join the swarm like the one below, run it on the worker machine.

shCopy
# To add a worker to this swarm, run the following command:
docker swarm join --token <your-join-token> <your-master-ip>:2377

That's it, if you go back to the Swarm tab, you will see the worker is now part of the swarm and Dokploy will be able to deploy services to it.

Exploration

Now what do I do with it?

With your Dokploy setup, you’re free to host anything you want! Personally, I use it to host services like this very blog that you are reading right now, Minecraft, Glance, Actual, Interval, my personal as well as client projects, and many more. If you’re still unsure what to host, you can explore this list of awesome self-hosted projects for inspiration.

Further actions

HTTPS for Dokploy

Go to the Server tab, Fill out your domain, and your Let's Encrypt email, and select Let's Encrypt as your certificate provider. Then hit Save.

Reload Traefik in the Web Server section, after reloading, your Dokploy is secured with HTTPS and you can safely close port 3000 in your firewall or security group.

Link your GitHub account

Linking your GitHub account to Dokploy allows you to deploy private projects directly from your repositories with ease. Once connected, you can select your private repositories, automate builds, and manage deployments seamlessly. This integration simplifies the process of keeping your applications up-to-date while maintaining control over your code.

Head over to the Git section, choose your Git provider, and authenticate with your Git account. Once connected, you can select your repositories and deploy them directly from Dokploy.

Dokploy has completely changed the way I manage my projects. It’s simple, flexible, and just works. If you’ve been juggling deployments or looking for a way to streamline your setup, give it a try—you might be surprised at how much easier it makes everything. Happy hosting!