Git over SSH is used as the deployment mechanism for Dokku-enabled servers.

Prerequisites

If you are already using Git for source control, let's say with GitHub, Bitbucket, or an internal Git server, then you do not need to install anything. Otherwise, install Git by following instructions for an external Website such as the Git SCM online book.

Your local git repository should be initialized:

git init

And your application source code should committed:

git add .
git commit -m "Initial commit"

Preparing Single Machine Environments

If you are using a single Healthcare Blocks server for your application, follow these instructions to prepare your application for deployment.

1. Ensure your public SSH key has been generated and added to your Healthcare Blocks server.

2. Ensure you've connected via SSH to your server and have created and configured your application as described in Dokku Getting Started Guide.

3. Define a Git remote on your local machine, pointing to your Healthcare Blocks server:

git remote add hcb dokku@server-id.healthcareblocks.com:my-app-name 

Note: hcb is an arbitrary label that can be anything and server-id and my-app-name will be based on your actual environment. The username should remain as "dokku" -- not your SSH username -- in order for deployments to succeed.

Preparing Multiple Machine Environments

If you are using multiple Healthcare Blocks servers in a high availability configuration, follow these instructions to prepare your application for deployment. 

1. Ensure your public SSH key has been generated and added to each of your Healthcare Blocks servers.

2. Ensure you've connected via SSH to each of your servers and have created and configured your application as described in Dokku platform introduction.

3. Define a Git remote on your local machine for the first Healthcare Blocks server:

git remote add hcb dokku@server-id-1.healthcareblocks.com:my-app-name

Note: hcb is an arbitrary label that can be anything and server-id-1 and my-app-name will be based on your actual environment.

4. For each additional machine, append another Git remote:

git remote set-url --add hcb dokku@server-id-2.healthcareblocks.com:my-app-name

Note: hcb should match the label you used for the first remote, and server-id-2 and my-app-name will be based on your actual environment.

Deploying Your Application

To deploy your application, use the following command:

git push hcb master

Notice "hcb" is the name of the Git remote you defined above. "Master" is the name of the branch you are pushing to on the server. This is always set to "master." 

If you are using a different branch locally, then adjust the above command to:

git push hcb local-branch-name:master

For example, if you have a local branch named integration:

git push hcb integration:master

Continuous Integration Environments

The above process is compatible with continuous integration environments. You will need to ensure the CI service's deployment key is distributed to your Healthcare Blocks servers.

Rolling Back Releases

There are two different ways to roll back. The easiest is to force push a previous git commit:

git push -f hcb de7fc85:master

where de7fc85 is the shortened git SHA for your commit.

Another approach involves tagging your releases when you deploy:

dokku tags:create my-app-name 1.0.1

Then, rolling back involves referencing the tag name:

dokku tags:deploy my-app-name 1.0.1

Troubleshooting

Error Message: "permission denied (publickey)"

Please refer to troubleshooting connection issues page.

Error Message: "Unable to select a buildpack"

Open source buildpacks use a detection script to check whether your deployed code represents an application written in NodeJS, PHP, Python, Ruby, etc. For example, here's the PHP detect script. If you receive this error, it indicates none of the buildpacks bundled with Dokku can detect your application type.

Ensure your application is structured and configured correctly. For example, PHP apps require a composer.json in the root of your source code repository.

Error Message: "broken pipe" or "remote hung up unexpectedly"

Update your SSH configuration to poll the server periodically so that it does not time out. The following instructions apply to Mac/Linux and Windows users using Git Bash:

  1. Edit ~/.ssh/config
  2. Add this line near the top of the file and save:
ServerAliveInterval 30

Error Message: "port 22: Operation timed out"

Possible causes: the intrusion detection system might have locked you out, or your IP address is different than what is registered under your account's IP address whitelist.

Check your connectivity via this command (replacing SERVER-ID and APP-NAME with your environment values):

git ls-remote -h dokku@SERVER-ID.healthcareblocks.com:APP-NAME

If you receive an error message or timeout, please contact us.

Error Message: "[remote rejected] master -> master (pre-receive hook declined)"

This error indicates there was a problem during the build step. Some common causes include: 

a) The version of the programming language executable used by your application is no longer supported in upstream repositories. This can happen if there was a security vulnerability, causing the version of the language executable to be yanked. Some of our quickstart guides list the current supported versions.

b) Your build environment is using an outdated buildpack. If you have a .buildpacks file in your app code respository or have set a BUILDPACK_URL env var, check if you have set a specific version. You can either remove the version (causing Dokku to use the latest version) or refer to the external buildpack repository to retrieve the latest version number.

c) If none of the above problems are applicable, please enable tracing, redeploy your application, and send us the output.

 dokku trace on