A guide to deploying Rails with Dokku on Aliyun

6 min readNov 18, 2020

The following is a step-by-step guide to deploying your Rails application with Dokku on an Aliyun 阿里云 (or Alibaba Cloud) ECS instance. I’ve opted to use Alibaba Cloud Elastic Compute Service (ECS) as I’m hosting my web application for use within China.

I will exclude details about Dokku and other technologies used in order to simplify this guide. Links will be available at the end if you wish to read more.

For reference, I’m running an ECS server with Ubuntu 20.04. You will also need to have a domain name in order to follow along.

Installing Dokku

First, connect to your server via SSH and ensure your server packages are up-to-date by running (Note: When you access your server for the first time, you’ll need an SSH key. I’ve added instructions at the bottom in case anyone is stuck on this step.)

apt update && apt upgrade

You may also run apt autoremove to remove any unused packages.

Next, grab the latest stable version of Dokku (v0.21.4 at the time of writing) and run the installation with the following:

wget https://raw.githubusercontent.com/dokku/dokku/v0.21.4/bootstrap.sh
sudo DOKKU_TAG=v0.21.4 bash bootstrap.sh

Modify the file/etc/hosts by running nano /etc/hosts and add 127.0.1.1 dokku.local on a new line. It should resemble the following. You may then ping dokku.local to test that it works.

127.0.0.1 localhost
127.0.1.1 dokku.local

In order to access the Dokku web installer, port 80 of the ECS instance has to be exposed to allow access to the web installer.

Visit the Elastic Compute Section in the Alibaba Cloud Console. Select your ECS instance and navigate to the Security Group settings. Click on Configure Rules on the relevant Security Group, and use the Quickly Create Rules button to allow access on port 80.

Now you can access the Dokku web installer by entering the IP address of your server (http://your.server.ip.address). If you have already added your SSH key to the server, this field will be auto-populated. Otherwise you’ll have to copy and paste your SSH key into the field, retrieve it by running cat ~/.ssh/id_rsa.pub.

Also take note to go through this step quickly, as your installation will be vulnerable to anyone who finds your setup page and inserts their SSH key.

Enter your domain name into the Hostname field (example.com) and tick the Use virtualhost naming for apps checkbox. Which means if you create an app called myapp, it will be accessible at myapp.example.com.

Click Finish Setup and you have successfully set up Dokku on your server! You may enter dokku on your server to view all available commands.

Deploying your Rails application with Dokku

Log into your server and create an app with Dokku

dokku apps:create myapp

I am also going to set up a postgres database, and there is a plugin for that. The following will install postgres, create a database and link it to our app:

dokku plugin:install https://github.com/dokku/dokku-postgres.gitdokku postgres:create railsdatabasedokku postgres:link railsdatabase myapp

Add domains to your app:

# Replace the domains with your owndokku domains:add myapp myapp.com
dokku domains:add myapp www.myapp.com

You’ll need to configure your domain’s DNS settings to point to the server.

Next, run the following command

dokku config:unset myapp DOKKU_PROXY_PORT_MAP

In your local, create a Dockerfile in the folder of your Rails app with the following contents. (Note that the buildpack method of deployment did not work for me, hence I’m using this Dockerfile)

FROM ruby:2.7.1# Install NodeJS and Yarn
RUN apt-get update
RUN apt-get -y install curl
RUN apt-get install -my gnupg
RUN curl -sL https://deb.nodesource.com/setup_10.x | bash -
RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -
RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list
RUN apt-get update && apt-get -qqyy install nodejs yarn && rm -rf /var/lib/apt/lists/*# Install Ruby Gems and node modules
COPY Gemfile* /tmp/
COPY package.json /tmp/
COPY yarn.lock /tmp/
WORKDIR /tmp
RUN gem install bundler -v 2.1.4
RUN bundle install --jobs 5 --retry 5 --without development test
RUN yarn install
RUN mkdir /app
WORKDIR /app
COPY . /app
ENV RAILS_ENV production
ENV RACK_ENV production# Execute the Procfile
CMD ["bin/run-dev.sh"]

Also create an app.json file with the following:

# Replace "myapp" to your app name{
  "name": "myapp", 
  "scripts": {
    "dokku": {
      "predeploy": "bundle exec rake assets:precompile",
      "postdeploy": "bundle exec rake db:migrate"
    }
  }
}

We will need to add our secret key. In our local, run rake secret. Copy the output, and it goes into your Dokku config variables.

dokku config:set myapp RAILS_ENV=production SECRET_KEY_BASE=paste-the-secret-key-here

As of Rails 5.2, we also have a master.key file. It decrypts the credentials.yml.enc that holds your secret_key_base (You may read some write-up about this in the next section). This has to be stored as a variable too, so copy the hash string from the master.key file and run:

dokku config:set myapp RAILS_MASTER_KEY=paste-the-hash-string-here

Finally add a remote repository to your rails app…

git remote add dokku dokku@your.server.ip.address:myapp

…and push your code to Dokku

git add .
git commit -m 'first commit'
git push dokku master

If everything goes well (🤞), your app is now deployed with Dokku!

Some bonus tips:

Turn dokku trace:on when deploying, it may help you debug problems
If your push hangs while deploying, run dokku apps:unlock myapp
For a continuous log, you can type dokku logs myapp -t

Configuring credentials

Without going into too much detail, you will store your private credentials in config/credentials.yml.enc. You need the proper file to decrypt it, which is your config/master.key.

You may use these commands to edit your credentials, then save and exit.

# With Vim
EDITOR=vim rails credentials:edit# Or with VS Code editor
EDITOR="code --wait" rails credentials:edit

The decrypted contents may look something like:

aws:
  access_key_id: 123
  secret_access_key: 345secret_key_base: example-of-hash-string

Adding free SSL with Let’s Encrypt

First install the Let’s Encrypt plugin by running:

dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git

Next run the following commands to configure and turn on the SSL

# Remember to replace "myapp" and "email@example.com"dokku config:set --no-restart myapp DOKKU_LETSENCRYPT_EMAIL=email@example.comdokku letsencrypt myapp

Finally set up auto-renewal

dokku letsencrypt:cron-job --add

Add a Swap file

If using a server with 2GB of ram or less, you may need to set up a swap. Otherwise your deployment process may run into issues.

Here are the steps to create a 2GB swap file:

sudo fallocate -l 2G /swapfilesudo chmod 600 /swapfilesudo mkswap /swapfile# You will see an output after this line

To activate the swap file:

sudo swapon /swapfile

To make the change permanent, open the /etc/fstab file and paste:

/swapfile swap swap defaults 0 0

You can check that the swap is active by running free -h to see the output.

“Where can I get the SSH key?”

Locate this page SSH Key Pairs in your Aliyun account, and click on Create SSH Key Pair. It will take you to a page to create the key and download it.

Then click on the bind option on your newly created key and assign it to your server. You can then use the key to access your server by typing:

ssh -i "yourkeyname.pem" root@your.server.ip.address

If you get a warning about permissions, adjust the file permissions by typing chmod 400 yourkeyname.pem.