Stay Ahead in Ruby!
From development processes to the most useful gems, get it all straight in your inbox. Join our Ruby blog today!

↓Skip to main content

Simplifying Application Deployment with Dokku: A Step-by-Step Guide

·6 mins
vladlytvynov development Dokku redis caddy deploy automation
Table of Contents
Simplifying Application Deployment with Dokku - cover image

What is Dokku? #

Dokku is a versatile open-source PaaS that simplifies app deployment. It auto-detects your app’s language, builds it from Git, and manages containers with technologies like nginx for routing.

Dokku also handles background processes and scheduled tasks, saving you manual effort. In summary, it’s an extensible, open-source solution that streamlines deployment.

What it does:

  • Build your app from source code automatically (detecting build flow with Buildpacks)
  • Build and run from existing Dockerfile
  • Make zero-downtime deploy
  • Automatically setup reverse proxy routing for apps
  • Run cron jobs

Let’s start! #

Installation of the Dokku is divided into 2 parts:

  • Server side - Installation and configuration of basic functionality on a remote server or VPS
  • Client side - local utility installation to connect and deploy code to the server

The entire article will consistently employ specific terminology to avoid any confusion regarding the origins of these elements.

Glossary:

  • new_app - your application name
  • 127.0.0.1.sslip.io - domain of your remote server to access it like google.com

On the Server #

Install Dokku: Follow the installation instructions to set up Dokku on your server.

# for debian systems, installs Dokku via apt-get
 wget -NP . https://dokku.com/install/v0.31.3/bootstrap.sh
 sudo DOKKU_TAG=v0.31.3 bash bootstrap.sh

Add SSH Key: Run the following command to add an SSH key for authentication:

cat ~/.ssh/authorized_keys | dokku ssh-keys:add admin

Set Domain: Configure the domain for your application using these commands:

dokku domains:set-global 127.0.0.1.sslip.io

Create Dokku Application: Create a new Dokku application on the server:

dokku apps:create new_app

Deployment #

Server side installation completed and we are ready to do deployment, and there couple options doing it.

There are 2 possible deployment options for Dokku:

  • Herokuish buildpacks
  • Dockerfile Let’s consider both options, but pay more attention to Dockerfile since this is a more familiar method for most

Buildpacks #

Dokku Buildpacks are similar in concept to Heroku Buildpacks but are used specifically within the Dokku environment.

There are buildpacks for almost any language or technology; you can see the list here.

Add the .buildpacks file to the root of the project and configure deployment via herokuish:

dokku builder:set new_app selected herokuish

Dockerfile #

While Dokku normally defaults to using Heroku buildpacks for deployment, you can also use Docker’s native Dockerfile system to define a container.

Change Dockerfile Path: Specify the path to your Dockerfile with this command:

dokku builder-dockerfile:set new_app dockerfile-path Dockerfile

GIT #

Change Deployment Branch (Optional): If needed, change the deployment branch for easier management:

dokku git:set --global deploy-branch #{YOUR_BRANCH}

Configuration #

Set Environment Variables: Configure environment variables for your application:

dokku config:set --no-restart new_app SOME=VARIABLE

Networking #

By default Dokku uses Nginx to route requests for corresponing app’s containers. But it is possible to reconfigure it and use Caddy instead, because Caddy’s automatic HTTPS setup with Let’s Encrypt ensures secure connections without the hassle of manual certificate management, making it an excellent choice for websites focused on security.

Change Nginx to Caddy: Switch from Nginx to Caddy as the web server:

dokku proxy:set new_app caddy
dokku nginx:stop
dokku caddy:start
dokku proxy:ports-add new_app http:80:5000

SSL Certificate: Obtain an SSL certificate for your application:

dokku caddy:set new_app tls-internal true
dokku caddy:set --global letsencrypt-email #{EMAIL}
dokku caddy:set --global letsencrypt-server https://acme-v02.api.letsencrypt.org/directory
dokku certs:generate new_app

Volumes (cache) #

Dokku volumes provide essential data persistence for Docker containers, ensuring that critical information, like databases or user uploads, remains intact across container restarts or scaling events. This will also avoid constant re-billing and reduce deployment time.

Mount some Directory: Set up the some directory for static data: dokku storage:ensure-directory #{SOME_DIRECTORY} dokku storage:mount new_app /var/lib/dokku/data/storage/some_directory:/new_app/some_directory

/var/lib/dokku/data/storage/some_directory - is a folder on the host server /new_app/some_directory - folder in app(container)

Plugins #

You are free to run almost anything in you Dokku setup and interact in the way you need. But most frequently needed things are aleady wrapped in Dokku Plugins for your convenience. These are Databases, Cache servers, Dokku flow customizations. All of these can be interacted via Dokku CLI, with no need to touch the server directly.

Dokku plugins provide a flexible way to adapt Dokku to your specific requirements and streamline your development and deployment processes. You can find a list of available plugins and installation instructions in the Dokku documentation or on the Dokku community website.

Plugins documentation See the official Dokku plugins list.

Plugin example #

Let’s look at an example of adding redis to an application and how easy it is.

Setup Redis: Install and configure Redis for your application: dokku plugin:install https://github.com/dokku/dokku-redis.git redis dokku redis:create redis -C "HOST=redis" dokku redis:link redis new_app --no-restart dokku config:set new_app REDIS_HOST="172.17.0.4" REDIS_PORT=6379 REDIS_PASSWORD=""

On client side #

Add Dokku Remote: Add the Dokku remote to your local Git repository:

git remote add dokku dokku@127.0.0.1.sslip.io:new_app

Push Your Code: Push your code to the Dokku remote, specifying the local and server branches:

git push dokku local_branch:branch_on_server

One-time Tasks #

You can run commands inside the application, just like in docker

dokku run new_app migrate

CI\CD #

Continuous Integration (CI) and Continuous Deployment (CD) are crucial practices in modern software development. When using Dokku as your hosting platform, you can set up a CI/CD pipeline to automate the process of deploying your application whenever changes are pushed to your code repository.

Here’s a step-by-step guide on how to implement CI/CD with Dokku:

1 Choose a CI/CD Service: #

Start by selecting a CI/CD service, such as Jenkins, Travis CI, CircleCI, GitLab CI/CD, or GitHub Actions. These services integrate with Git repositories and allow you to automate the CI/CD pipeline.

2 Set Up Your CI/CD Workflow #

Create a configuration file (e.g., .gitlab-ci.yml for GitLab CI/CD or .github/workflows/deploy.yml for GitHub Actions) in your project’s repository to define your CI/CD workflow.

Below are basic example of pipelines for popular Git systems:

GitHub Actions #

name: 'deploy'

on:
  push:
    branches:
      - production

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Cloning repo
        uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Push to Dokku
        uses: dokku/github-action@master
        with:
          branch: 'main'
          git_remote_url: 'ssh://dokku@127.0.0.0:22/new_app'
          ssh_private_key: ${{ secrets.SSH_PRIVATE_KEY }}

GitLab CI #

image: dokku/ci-docker-image

stages:
  - deploy

variables:
  GIT_DEPTH: 0

deploy:
  stage: deploy
  only:
    - master
  variables:
    GIT_REMOTE_URL: ssh://dokku@127.0.0.0:22/new_app
  script:
    - dokku-deploy
  after_script:
    - dokku-unlock

3 Configure CI/CD Secrets #

If your CI/CD service requires credentials or access to your server, store sensitive information like SSH keys or environment variables as secrets or securely encrypted variables in your CI/CD platform. Refer to your CI/CD service’s documentation for guidance on setting up secrets.

4 Trigger CI/CD Pipeline #

Commit and push changes to your Git repository. Your CI/CD service should automatically detect the changes and trigger the CI/CD pipeline defined in your configuration file.

5 Monitor and Debug #

Monitor your CI/CD pipeline for any errors or issues. Most CI/CD services provide logs and notifications to help you debug any problems that arise during the deployment process.

6 Access Your Deployed App #

Once you’ve configured your CI/CD pipeline, monitor its status in your CI/CD service’s dashboard. It should automatically build and deploy your application whenever changes are pushed to the main branch of your Git repository.

With this setup, your application deployments on Dokku will be automated, ensuring that your application stays up-to-date with the latest changes in your codebase.

Conclusion #

Deploying applications can be simplified with Dokku’s features and streamlined process. By following the step-by-step guide above, you can set up Dokku, configure your application, and push your code with ease. Give Dokku a try and experience a smoother deployment workflow for your projects.

We are ready to provide expert's help with your product
or build a new one from scratch for you!

Contact MobiDev’s tech experts!
↑