Git over SSH is used as the deployment mechanism for Dokku-enabled servers.
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:
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 email@example.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 firstname.lastname@example.org: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 email@example.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 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
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:
- Edit ~/.ssh/config
- Add this line near the top of the file and save:
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 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] 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. 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