[Dokku] How to set up dokku to deploy docker image

About installing the dokku, I have written another post before: How to install Dokku with Portainer. So I will assume that you have Dokku installed in your server in this post.

1. Environment Setting

1. Dokku: version: 0.27.5. HTTP port: 80, HTTPS port: 443, SSH port: 5022
2. IP of remote server where the Dokku is installed: 166.23.44.25 (example)
3. Domain: example.com
4. Name of App that will be deployed by Dokku: blog
5. Port of App: 3000

2. SSH Configuration

1. Generate ssh key public file id_rsa.pub

ssh-keygen -o

We will name the file as dokku_rsa, then you will see two files are generated: dokku_rsa and dokku_rsa.pub.

2. Place the file dokku_rsa.pub into the Dokku container and you can add a ssh key against Dokku with

dokku ssh-keys:add <key_name> path/to/dokku_rsa.pub  
# Test whether the ssh key is added
dokku ssh-keys:list

3. Place the file dokku_rsa into the localhost and add below code into ~/.ssh/config.

Host example.dokku
  HostName 166.23.44.25
  Port 5022
  IdentityFile path/to/dokku_rsa

Now you can check if the ssh config works by

ssh example.dokku

If you can see the prompt of “Enter passphrase for key xxx” pops up, it means the configuration is right.

3. Set up Dokku app

1. In remote server, login Dokku container first.

docker exec -it <dokku_container_name> /bin/bash

2. Create the first Dokku app blog

dokku apps:list
dokku apps:create blog

3. Add domain to the app blog

dokku domains:set blog blog.example.com
# Add global domain
dokku domains:set-global example.com
# Check the domain setting  
dokku domains:report

4. When Dokku is installed with docker-compose, we need to set up app’s initial network.

dokku network:set blog initial-network <dokku_network>

5. Set port mapping to the app’s port

# As dokku listens to port 80, host port should be 80
dokku proxy:ports-set blog http:80:3000

With this setting, we can make sure that the blog docker container can start with the same network where the Dokku container is. So that Dokku nginx can proxy the requests to the app.

6. Check app’s configuration

dokku config:show blog

The output should look like

=====> blog env vars
DOKKU_APP_RESTORE:       1
DOKKU_APP_TYPE:          dockerfile
DOKKU_DOCKERFILE_PORTS:  3000
DOKKU_PROXY_PORT:		 80  
DOKKU_PROXY_PORT_MAP:    http:80:3000
GIT_REV:                 62f46782a3ad6dc6932f9089a4c3e655da888813

4. Configure git on localhost

1. Add Dokku remote repository

# Remove the existing remote repository
git remote rm dokku
# Add remote repository
git remote add dokku dokku@example.dokku:blog

2. Deploy the project with Dokku

git push dokku master

If everything is set up correctly, after pushing the repository to dokku, the output should show the message like Application deployed: http://blog.example.com.

5. Your repository

1. If you want to deploy a docker image, you’ll need to put the Dockerfile on the root directory of the project.

2. The Dockerfile needs to expose the port which the server listens. For example, if your service listens to the port 8060, then you need to expose port 8060 in the Dockerfile.

6. Troubleshooting

1. Error insufficient_scope: authorization failed

The whole error may look like

Failed to solve with frontend dockerfile.v0: failed to create LLB definition: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed 

The error might be caused by git push dokku master. Running the below command in Dokku container may solve the issue.

echo "export DOCKER_BUILDKIT=0" | sudo tee -a /etc/default/dokku

2. web browser shows We're sorry xxx

It means that your Dokku server can be reached, but some problems happens when Dokku nginx proxy the requests to app service. There is a high chance that the incorrect port mapping brings this issue. Check out how the port mapping looks like

# Show app's port mapping 
dokku proxy:report <app_name>
# Update app's port mapping 
dokku proxy:ports-set <app_name> http:<dokku_port>:<app_port>
# Check if the nginx configuration is updated
dokku nginx:show-config <app_name>

More useful commands can refer to another post Dokku Handbook.