This article applies to environments with the Dokku PaaS installed. If you're using a legacy environment and would like to leverage this framework, please create a support ticket.
Dokku is a Platform-as-a-Service Framework
Dokku is a lightweight platform for single machine environments that provides Heroku-like functionality for managing applications, their configurations, SSL certificates, and running one-off commands. Internally, Dokku uses open source Heroku "buildpacks" to be able to run applications representing the many combinations of popular programming languages and frameworks. Dokku applications are deployed to the Healthcare Blocks platform using Git from your local machine or continuous deployment service.
Dokku is also an open source project. While our documentation addresses most of Dokku features, the official documentation (external site) can be helpful if you're looking to go deeper.
Dokku is based on the concept of The 12 Factor App. Here are benefits/differences compared to the traditional way of deploying code to a virtual machine.
When code is deployed (via git) to the server, it is compiled into an "image" based on the popular Docker framework. This image is then run as a "container" during runtime. This revolutionary approach provides several benefits:
- Application dependencies are encapsulated within application-specific Docker images. As framework and library versions evolve, they are easier to manage without needing to worry about what is installed on the virtual machine itself.
- Ability to run more than one app or service on the same machine and mix and match different technology stacks without worrying about conflicts. If you are deploying multiple micro-services, this benefit is significant.
- Zero downtime deployments. As a new build is being created, the previous one continues to function as your active application. Dokku also provides status checks that prevent a bad build from going live.
- Containers can be easily scaled out within a few seconds. This feature is useful if you are anticipating a surge in traffic and need your app to support greater concurrency.
Everything is Configuration Driven
Instead of installing components and libraries manually on the server itself, dependencies are specified in configuration files stored in your source code, specific to your app type. For example, PHP apps use composer.json and Node.js apps use package.json. These config files are detected by Dokku during the deploy / build step and any missing libraries are automatically installed.
Environment-specific settings are stored in environment variables. If your app uses a production-specific configuration, instead of hardcoding them in source code, you can use Dokku to persist them on the server.
Where's the Filesystem?
Application containers have an "ephemeral" filesystem. Any dynamic content generated within a container will go away upon the next deployment. Containers are meant to be disposable and quickly and easily replaceable by a new app build. So how do we deal with user generated content? Dokku allows you to define a permanent storage mount that lives outside of the container but is accessible by the container. This way, if the container is replaced, the new container can still access previously generated files. See the Storing Uploaded Files section below for details.
Quick Start Guides
Installing Command Line Interface (CLI) Tools
This is an optional step, since you can run Dokku commands directly on the server while connected via SSH. But if you prefer to interact with your application directly from your local machine, see the Clients page for additional information. Please be sure you've confirmed you can connect via SSH before attempting to use the CLI from your local machine.
Preparing your Project
Your application must be stored in a local Git repository. Please refer to the Git prerequisites.
Next, add a Procfile to the root of your Git repository. A Procfile is a "process file" that instructs Dokku how to run your application or service and must include a process defined as "web" if you are running a Web application:
# NodeJS example web: node index.js # Python Django example web: gunicorn myproject.wsgi --log-file -
If your application uses a background process to do work, let's say a job queue processor, you can also include a worker declaration:
# Ruby on Rails Delayed Job Example worker: bundle exec rake jobs:work
If you have questions about Procfiles for your app, please create a help desk ticket.
Creating an Application
Connect to the server and create your app(s):
ssh firstname.lastname@example.org dokku apps:create my-app-name
Setting Application Configuration Variables
We recommend using environment variables to store production-specific settings such as database connections, API keys, and other secrets that you don't want to store in your repository code. On the server, do:
dokku config:set my-app-name KEY1=VALUE1
To view config variables, do:
dokku config my-app-name
Note: you can set environment variables before you deploy your application for the first time. This way, if any deployment build steps depend on a production-specific variable, your first deployment won't fail.
- Dokku reference: environment variables
If you provisioned a plan from the Healthcare Blocks database-as-a-service, you should have received database credentials. Please contact us if you need them again.
Some application frameworks enable you to define the database connection string in a URL format. If your application and database type support this format, you can set the connection string as an environment variable:
dokku config:set my-app-name DATABASE_URL="mongodb://database-user:database-password@server-address/database-name?ssl=true"
For a replicaset:
dokku config:set my-app-name DATABASE_URL="mongodb://database-user:database-password@server-address-1,server-address-2,server-address-3/database-name?ssl=true"
dokku config:set my-app-name DATABASE_URL="postgres://database-user:database-password@server-address/database-name?sslmode=require"
Deploying Your Application
Setting a Domain Name
Restarting, Scaling, and One-Off Commands
Persisting Uploaded Files
See the how to import a database topic.
Adding Other Team Members
If you'd like for other members on your team to be able to deploy via Dokku, please contact us.
Setting Resource Limits
See this topic.
Frequently Asked Questions
Can I deploy more than one application to my server?
Yes! Just follow the steps, "Preparing Your Project," "Creating an Application", and "Setting Application Configuration Variables" for each application or micro-service you'd like to deploy. Then refer to the Deploying via Git to a Dokku server page for instructions on creating a deployment git remote.
Please refer to these sample Heroku reference apps to see example configurations, including Procfiles. All of these apps are compatible with Dokku.