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"

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

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

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

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

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

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

Note: hcb should match the label you used for the first remote.

Deploying Your Application

To deploy your application, use the following command:

git push hcb main

Notice "hcb" is the name of the Git remote you defined above. "Main" (formerly referred to as "Master") is the name of the branch you are pushing to on the server and should not be changed.

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

git push hcb local-branch-name:main

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

git push hcb integration:main

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

You can force push a previous git commit:

git push -f hcb de7fc85:main

where de7fc85 is the shortened git SHA for your commit.

Or if you've created a new branch off of a previous commit or git tag, you can reference the branch during deployment:

git push -f hcb rolling-back-feature-x:main

Troubleshooting

Error Message: "permission denied (publickey)"

Please refer to troubleshooting connection issues page.

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 access list.

Check your connectivity via this command (replacing server-id and my-app with your actual values):

git ls-remote -h dokku@server-id.healthcareblocks.com:my-app

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

Error Message: "[remote rejected] main -> main (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.

b) Your build environment is using an outdated buildpack. Refer to the "Stack Specific Guides" on Dokku - Getting Started to read about how to update the buildpack to use the latest version.

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

dokku trace:on