How to Use Dokku: The Beginner's Guide (First VPS, First Git-Push Deploy, the Buildpacks Lesson, and SSL)

CodexFuse Team · 2026-11-07T00:06:33.232Z · 21 min read min read

How to Use Dokku?

Learning how to use dokku takes seven moves: provision a VPS, install Dokku with the bootstrap script, set your SSH key and global domain, create your first app, push your code with Git, add a database, and enable free SSL. Dokku is an open-source Platform as a Service that turns one Linux server into your own mini heroku, and it builds your apps from a git push with Heroku buildpacks or a Dockerfile. This dokku tutorial follows the official installation and deployment docs for the current release, v0.38.34, with every fact checked in November 2026.

Dokku runs on Docker, so a basic grip on containers helps before you start. The Docker beginner guide on CodexFuse covers images, containers, and compose in one sitting if you need a refresher. You do not need to install Docker yourself, because the Dokku installer brings it along.

This guide sits in the self-hosted PaaS cluster opened by the VPS hosting guide on CodexFuse, which covers picking and securing the server Dokku runs on. Dokku is the sibling lane in that cluster: the git-push deploy layer that sits on top of the VPS.

1. Provision a fresh Ubuntu 24.04 VPS with at least 1 GB of RAM.
2. Install Dokku v0.38.34 with the official bootstrap script.
3. Add your SSH key and set your global domain.
4. Create your first app with dokku apps:create.
5. Push your code with git push dokku main.
6. Add a database with the official Postgres plugin.
7. Point a domain at the app and enable free SSL with Let's Encrypt.

What Is Dokku?

A dokku install turns one Linux server into a small, open-source Platform as a Service that runs on a single server of your choice. Its own tagline is "The smallest PaaS implementation you've ever seen," and its homepage calls the result your own, single-host version of Heroku. You push Heroku-compatible apps to it with Git, it builds them with Heroku buildpacks or a Dockerfile, and it runs them in isolated containers behind nginx.

The project started on 8 June 2013, created by Jeff Lindsay, and it is maintained today by José González. It is free and open source under the MIT license, with 32,220 GitHub stars and 2,099 forks as of this run.

The repository is 4,900 days old, which is 13.4 years, and it works out to 15.35 stars per fork with only 0.1 open issues per 100 stars. The last push to the repository landed on 6 November 2026, so the project is actively maintained.

CodexFuse offers no Dokku tool; this guide teaches the official install, and nothing in it depends on a CodexFuse product. Dokku uses nginx and cron under the hood: web processes are routed automatically, while background processes and automated cron tasks are also managed. That is the whole mental model: one server, one git push, one live app.

What Do You Need Before You Install Dokku?

You need a clean server, a domain, and an SSH key before the installer runs. The installer takes over nginx on first run, so never install Dokku on a server that already serves live websites. Start with a fresh VPS and keep the checklist below beside you.

The disk row deserves a pause. The official docs state no disk minimum, and the 20 GB figure is the ComputingForGeeks recommendation only.

Their lab VM went from 2.6 GB used to 8.1 GB after two small demo apps, which is 5.5 GB added and 3.12 times the starting use. The buildpack builder image alone is 1.43 GB, which is 7.15 percent of a 20 GB disk. Start with 20 GB and you will not be resizing the disk after your second app.

How Do You Install Dokku on a VPS?

Install Dokku with the official bootstrap script, pinned to the current release. The commands below are verbatim from the official installation docs, fetched this run. Pin the version in the command, because the docs track master and already mention features from the unreleased 0.39.0 line.

wget -NP . https://dokku.com/install/v0.38.34/bootstrap.sh
sudo DOKKU_TAG=v0.38.34 bash bootstrap.sh

The install takes about 5 to 10 minutes depending on connection speed. The ComputingForGeeks walkthrough, which actually ran it on a 2 vCPU and 4 GB VM, finished in 203 seconds, which is 3.38 minutes.

After the install it reported Dokku 0.38.34, Docker 29.9.2, and nginx 1.28.3. The script installs Docker from Docker's own repository, adds the Dokku apt repository, and pulls in nginx, herokuish, plugn, and sshcommand.

One warning from that same walkthrough: use a clean server, because the installer takes over nginx and removes whatever is in the sites-enabled folder on first run. The script pauses for 10 seconds to warn you about this before it proceeds. Ports 22, 80, and 443 must be reachable from the internet if you want Let's Encrypt certificates later.

How Do You Set Your SSH Key and Global Domain?

Set your SSH key and global domain right after the install finishes. The bootstrap script adds the keys in root's authorized_keys file and sets the server IP as the global domain when those are not already configured. The commands below are verbatim from the official docs, and they finish the setup by hand.

cat ~/.ssh/authorized_keys | sudo dokku ssh-keys:add admin
dokku domains:set-global dokku.me
dokku domains:set-global 10.0.0.2
dokku domains:set-global 10.0.0.2.sslip.io

Use your own domain in place of dokku.me, and your own server IP in place of 10.0.0.2. The domain needs an A record or CNAME pointing at your server IP.

A wildcard domain record lets apps live at app subdomains, while a single domain serves apps on a random port instead. The sslip.io form gives you subdomain support from a bare IP address when you own no domain yet.

The web installer also appears on first boot, on port 80, asking for a public key and the virtualhost naming choice. Finish it right after the install, because the install page stays open until the wizard has been completed once. That first screen is also where the admin account is created, so do not leave the server sitting with an unfinished installer.

How Do You Deploy Your First App with Git Push?

Deploying your first app is three commands: create the app, add the remote, and push. The example below uses Heroku's Ruby sample app, exactly as the official deployment docs show it. If your code lives on GitHub, the GitHub beginner guide on CodexFuse covers cloning it down first, and the Git beginner guide covers the Git commands themselves if they are new to you.

git clone https://github.com/heroku/ruby-getting-started
dokku apps:create ruby-getting-started
cd ruby-getting-started
git remote add dokku [email protected]:ruby-getting-started
git push dokku main

The remote username must be dokku, or pushes will fail. Replace dokku.me with your own domain or server IP.

Dokku builds the app on the server, starts a container from the built image, and prints the live URL when the deploy succeeds. A successful deploy ends with the application URL on your domain, in the form app-name dot your domain.

Your app must respect the PORT environment variable, or it may not respond to web requests. Dokku sets PORT for the container, and your app should listen on it instead of a hardcoded port.

To rebuild an app after a config change, run the rebuild command below. To rebuild and tag an image without deploying it, set skip-deploy to true first.

dokku ps:rebuild ruby-getting-started
dokku ps:set ruby-getting-started skip-deploy true
dokku config:set ruby-getting-started NODE_ENV=production

App names must be lowercase, and a name with dots is treated as a full hostname. Apps are created on the fly on the Dokku server when pushed, so creating the app first is a formality that keeps the name reserved. That is the whole dokku deploy flow: create, remote, push, live.

The Buildpacks Lesson: How Dokku Chooses a Builder

Dokku picks a builder by detection order, and the order is herokuish, then pack, then Dockerfile. This is the one lesson that saves beginners the most confusion, because a repo that contains both a Dockerfile and a buildpack signal will not use the builder you expect. Learn the order once and you will never debug a surprise build again.

Herokuish is the default, and it auto-detects your language the way Heroku does. The pack builder needs the pack command-line tool installed separately, because it is not bundled with Dokku, and it cannot pick specific buildpacks yet. The Dockerfile builder is the last resort in the detection order, and the docs call it a power-user feature, because you lose the comforts buildpack users get, like automatic port wiring.

The gotcha works both ways. If your repo has a Dockerfile in the root, Dokku uses it, but a .buildpacks file or a BUILDPACK_URL variable overrides that and forces buildpacks.

If you switch builders on an existing app, clear the port mapping first, or the old mapping survives the switch. The commands below show the builder controls in one place.

dokku builder:set my-first-app selected herokuish
dokku builder:set my-first-app selected pack
dokku builder-dockerfile:set my-first-app dockerfile-path .dokku/Dockerfile
dokku ports:clear my-first-app

On non-AMD64 platforms, herokuish is blocked by default and needs an explicit allow flag. That matters on arm64 servers, where a first deploy can fail with a builder error that looks like a broken app. Follow the current official docs for the exact flag, because the builder docs move faster than the guides that quote them.

How Do You Add a Database to Dokku?

Dokku ships with no datastores, so a dokku database comes from an official plugin. The plugin system is built on plugn, and the Dokku project provides official plugins for Postgres, MySQL, MariaDB, Mongo, Redis, and more. The Postgres workflow below is verbatim from the official docs and the plugin readme.

sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git
dokku postgres:create railsdatabase
dokku postgres:link railsdatabase ruby-getting-started

Linking sets the DATABASE_URL environment variable on your app, so the app reads its connection string the same way it would on Heroku. The Postgres plugin currently defaults to installing Postgres 18.6, and it requires Dokku 0.35.x or newer. Plugin installs need root or sudo, except for listing plugins and viewing plugin help.

The plugin also gives you info, list, logs, export, import, and backup commands for each service, plus expose, connect, and restart controls. Backups go to an S3 bucket with the backup command, so a database is not trapped on the one server. Every datastore is also served by the built-in datastore plugin, so the pattern stays the same no matter which database you pick.

How Do You Add a Domain and SSL to Dokku?

Add a domain to the app first, then enable SSL on it. Dokku SSL comes from the official Let's Encrypt plugin, which issues free certificates and renews them on a daily cron job. The app must already be deployed and publicly reachable over plain HTTP before a certificate can be issued, and every domain on the app must point at the server's public IP.

dokku domains:set ruby-getting-started ruby-getting-started.your.domain.com
dokku domains:report ruby-getting-started
dokku certs:add ruby-getting-started server.crt server.key

The certs:add command is the route for your own certificate, when you already hold one. The Let's Encrypt route needs the plugin installed first, then your email set, then the enable command, then the cron job for renewals. The commands below are verbatim from the official deployment docs and the plugin readme.

sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
dokku letsencrypt:set --global email [email protected]
dokku letsencrypt:enable ruby-getting-started
dokku letsencrypt:cron-job --add

The cron job renews certificates daily at 06:24, which is 384 minutes after midnight, when the Dokku cron plugin is installed. Without it, the renewal lands in the dokku user's crontab as a daily job. The plugin uses the lego ACME client, with HTTP-01 challenges by default and DNS-01 supported for wildcard domains.

One stale command still circulates in old guides: the one-liner that runs letsencrypt with just the app name. That form is outdated, and the current command is letsencrypt:enable with the app name. If a guide shows the old form, the guide predates the current plugin, and its other commands deserve the same suspicion.

Dokku vs Coolify: Which One Fits You?

Choose Dokku if you like the git push workflow and are happy in a terminal, and choose Coolify if you want a dashboard. That line comes from Coolify's own comparison page, and it is the honest split. Both are free and open source, both run on your own server, and both replace Heroku for small teams, but they aim at different people.

The Coolify beginner guide on CodexFuse covers the dashboard side of this choice in full. Read it if the table below leans you toward a web UI, because the two guides together cover the whole self-hosted PaaS decision. Dokku stays a single-server tool, so multi-server setups need custom scripts or the optional Kubernetes scheduler.

CapRover sits between the two: a web UI like Coolify but Docker-focused like Dokku, free and open source, with multi-server support and no Heroku buildpacks. The RAM figures for Coolify come from independent comparisons, not from Coolify's own docs, so treat them as reported measurements. On a 1 GB VPS, the choice is already made for you, because Coolify will not fit comfortably.

What Does Dokku Cost?

Dokku itself costs nothing, because the core is free and open source under the MIT license. Your only bill is the VPS it runs on, and the independent guides use a 5 to 6 dollar VPS as their example. One dev.to guide reports a solo developer hosting 8 side projects on a 6 dollar DigitalOcean droplet.

Dokku Pro is the paid add-on, and it costs 849 dollars for life on the official Pro site. It is a one-time lifetime license with free upgrades forever, and it covers 1 production server plus 2 pre-production servers.

It adds a full web UI, a JSON API, HTTPS git push support, team management, and email support. The site warns that the price reflects an early-bird discount while the product is in development, and it may rise, so check the current price before budgeting.

from datetime import date
today = date(2026, 11, 7)
rel = date(2026, 10, 30)
created = date(2013, 6, 8)
devto = date(2026, 3, 29)
print("days since v0.38.34 release:", (today - rel).days)
print("days since repo created 2013-06-08:", (today - created).days)
print("years since repo created:", round((today - created).days / 365.25, 1))
print("stars per fork:", round(32220 / 2099, 2))
print("open issues per 100 stars:", round(32 / 32220 * 100, 2))
print("Dokku Pro 849 dollars vs 5 dollar VPS months:", round(849 / 5, 1))
print("Dokku Pro 849 dollars vs 5 dollar VPS years:", round(849 / 5 / 12, 1))
print("buildpack image 1.43 GB of 20 GB disk percent:", round(1.43 / 20 * 100, 2))
print("install 203 seconds in minutes:", round(203 / 60, 2))
print("disk growth 2.6 to 8.1 GB added:", round(8.1 - 2.6, 1))
print("disk growth ratio:", round(8.1 / 2.6, 2))
print("dev.to guide age days:", (today - devto).days)
print("letsencrypt cron 06:24 is minutes after midnight:", 6 * 60 + 24)
print("Coolify min RAM 2 GB vs Dokku 1 GB ratio:", 2 / 1)
print("Coolify idle RAM low end 500 MB vs Dokku 50 MB ratio:", 500 / 50)

The computed block above ran this run, and its outputs are the numbers quoted in this guide. The most telling one is the Pro comparison: 849 dollars buys 169.8 months of a 5 dollar VPS, which is 14.2 years of server time. The web UI is a convenience purchase, not a running cost, and most beginners should run the free core for months before deciding they need it.

Seven Mistakes Beginners Make with Dokku

Every mistake below comes from a real failure mode in the sources for this guide. Read the table once before your first install, and you will skip the debugging session that teaches each one the hard way.

Sources

The official docs carry this guide: the installation page for the system requirements and bootstrap commands, the application deployment page for the first deploy, Postgres, and Let's Encrypt flows, the builder pages for herokuish, Cloud Native Buildpacks, and Dockerfiles, the domains page for vhost rules, the plugin pages for the datastore list, and the enterprise page for Dokku Pro. The GitHub API supplied the release data for v0.38.34, published 30 October 2026, and the repository metadata: created 8 June 2013, MIT license, 32,220 stars, 2,099 forks, 32 open issues, last push 6 November 2026.

The plugin readmes for dokku-postgres and dokku-letsencrypt supplied the Postgres 18.6 default, the 0.35.x requirement, and the 06:24 renewal time. All of these were fetched on 6 and 7 November 2026.

The independent guides filled in the tested numbers: the ComputingForGeeks walkthrough from November 2026, which actually ran the v0.38.34 install and reported 203 seconds, Docker 29.9.2, and nginx 1.28.3, plus the 20 GB disk recommendation and the 2.6 to 8.1 GB growth figure; the dev.to guide from 29 March 2026, which pins the older v0.34.4 release and reports 8 side projects on a 6 dollar droplet; the CodingMatty guide from around June 2026, which deploys the real Linkwarden app; and the Bomberbot guide, which has no publish date shown and still uses the old install method and Heroku free-tier references. The comparisons came from Coolify's own comparison page, the dev.to PaaS comparison from October 2026, the ecn-apps comparison, and the MassiveGRID comparison.

No testbed outputs were executed for this guide, and no search volumes were researched, so no traffic or popularity numbers appear anywhere above. Every number in the article comes from the sources named in these paragraphs or from the computed block, which ran this run. Where sources disagree, the article says so: the idle RAM figures differ across third-party comparisons, the 20 GB disk figure is a walkthrough recommendation rather than an official minimum, and the Bomberbot guide carries no verifiable publish date.

Frequently Asked Questions

Is Dokku really free?

Yes, the Dokku core is free and open source under the MIT license, with no paid tiers for the core product. Dokku Pro is an optional 849 dollar lifetime add-on that buys a web UI, a JSON API, and HTTPS git push support.

How much RAM does Dokku need?

Dokku needs 1 GB of RAM at minimum with the Docker scheduler, and the K3s scheduler needs 2 GB on every node. Independent comparisons put idle use under 50 MB, which is why Dokku fits on the smallest VPS plans.

Do I need Docker installed before Dokku?

No, the bootstrap script installs Docker from Docker's own repository as part of the install. You only need a fresh Ubuntu or Debian server with SSH access and sudo.

Can I deploy with a Dockerfile instead of buildpacks?

Yes, Dokku uses your Dockerfile when no herokuish or pack signal is detected in the repo. The detection order is herokuish first, then pack, then Dockerfile, so a .buildpacks file or a BUILDPACK_URL variable overrides a root Dockerfile.

How do I update Dokku to a new release?

Each release body on GitHub gives install and update commands for that exact version. Re-run the bootstrap script with the new version tag in DOKKU_TAG, and check the release notes first for breaking changes.