We hope you find this tutorial helpful. In addition to guides like this one, we provide simple cloud infrastructure for developers. Learn more →

How To Use the Dokku One-Click DigitalOcean Image to Run a Go App

PostedNovember 27, 2013 13.1k views Dokku One-Click Install Apps PostgreSQL Git Ubuntu

Note: The Dokku project has changed significantly since this guide was written. The instructions below may not reflect the current state of the Dokku project.

Introduction


A significant hurdle in developing an application is providing a sane and easy way to deploy your finished product. Dokku is a Platform as a Service solution that enables you to quickly deploy and configure an application to a production environment on a separate server.

Dokku is similar to Heroku in that you can deploy to a remote server. The difference is that Dokku is built to deploy to a single, personal server and is extremely lightweight. Dokku uses Docker, a Linux container system, to easily manage its deployments.

In this guide, we will cover how to deploy a Go app with Dokku using the DigitalOcean Dokku one-click installation image.

Step One –– Create the Dokku Droplet


The first thing we need to do is create the VPS instance that contains our Dokku installation. This is simple to set up using the DigitalOcean Dokku application.

Click on the "Create" button to create a new droplet:

DigitalOcean create droplet

Name your droplet, and select the size and region that you would like to use:

DigitalOcean configure droplet 1

Scroll down and click on the "Applications" tab. Select the Dokku application image:

DigitalOcean Dokku image

Select your SSH keys if you have them available. If you do not already have them configured, now is a great time to create SSH keys to use with your DigitalOcean droplets. This step will help you later.

Click "Create Droplet". Your Dokku VPS instance will be created.

DigitalOcean final create

Once your droplet is created, you should set up your domain name to point to your new Dokku droplet. You can learn how to configure domain names with DigitalOcean here.

Step Two –– Access the Droplet To Complete Configuration


You can complete your Dokku configuration by accessing your VPS from a web browser.

If you configured a domain name to point to your Dokku installation, you should visit your domain name with your favorite web browser. If you do not have a domain name configured, you can use your droplet's IP address.

You will be given a simple configuration page. There are a few parts that you need to configure here.

DigitalOcean Dokku ssh keys

First, check that the Public Key matches the computer that you will be deploying from. This means that if your project is on your home computer, you should use the public key that corresponds to that set up.

If you selected multiple SSH keys to embed during droplet creation, only the first will be available here. Modify it as necessary.

DigitalOcean Dokku hostname configuration

Next, modify the Hostname field to match your domain name. Leave this as your IP address if you do not have a domain name configured.

Choose the way that you want your applications to be referenced. By default, the application will be served like this:

http://your_domain.com:app_specific_port_number

If you select the "Use virtualhost naming for apps" check box, your apps will be accessible using a virtualhost instead:

http://app_name.your_domain.com

Click the "Finish Setup" button to complete the configuration.

Step Three –– Deploy your Go Web App using Dokku


Now that you have your Dokku droplet configured, we can start thinking about how to deploy our Go application.

To demonstrate some more complex functionality, we will have our Go application interface with a PostgreSQL database and print some rows from that.

Install the PostgreSQL Plugin and Initialize an Application Database


Dokku adheres to a philosophy that application resources should be handled as separate, interchangeable pieces. This means that databases are not incorporated snugly into the application code, but instead are handled as external resources.

This allows you to easily change either the code or the database without affecting the other part. They are separate, but can be linked together easily and effortlessly.

Dokku implements this kind of functionality through a plugin system. Dokku has a full list of plugins that you can use to extend the functionality of the core program. This means that you don't have to incorporate extraneous code on your production server if your projects do not require the functionality they provide.

To install the PostgreSQL plugin directly from GitHub, run:

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

If you issue the dokku help command, you can see that Dokku has already incorporated PostgreSQL functionality within our environment:

dokku help

. . .
plugins         Print active plugins
postgres:create <app>     Create a PostgreSQL container
postgres:delete <app>     Delete specified PostgreSQL container
postgres:info <app>       Display database informations
postgres:link <app> <db>  Link an app to a PostgreSQL database
postgres:logs <app>       Display last logs from PostgreSQL container
run <app> <cmd>                                 Run a command in the environment of an application
. . .

We have the PostgreSQL commands available, so let's make a database for our application:

dokku postgres:create app_name

The app_name in this command is pretty important. It must match the name that you will choose for your project, which in turn, decides the URL you will use to access your application if you set up virtual hosts during Dokku configuration:

http://app_name.your_domain.com

This command will output some connection information for the database. This is accessible at any time by typing:

dokku postgres:info app_name

In most cases, you will not have to use this information directly, because once your application is pushed, it will create an environmental variable called DATABASE_URL which you can use to connect to the database within your code.

Getting a Go Application to Deploy


On your development machine (the machine with the SSH key that matches the one you selected when setting up Dokku), we will be configuring our Go application. This machine needs to have git installed in order to properly connect to our Dokku server.

You can find instructions on how to install git on various platforms on the GitHub software. If you are on Ubuntu or Debian, you can simply type:

sudo apt-get install git

For our Go application to correctly hook into our Dokku environment, we're going to require the use of a few libraries. We need to "os" library to have access to the DATABASE_URL environmental variable, the "net/http" library to serve our web requests, and the "database/sql" and "lib/pq" libraries to handle the database interactions.

Rather than trying to write a program from scratch, let's clone a sample application from GitHub. Go to your home directory and clone it:

cd ~
git clone https://github.com/imchairmanm/go_test.git

Change into the project's directory:

cd go_test

Here, we can see a few things that are necessary for your Go program to function correctly with Dokku.

  • Procfile: This file defines the command needed to start the Go web service. In this case, this file points to the web.go file with the line web: web.go, which is our main program.

  • .godir: This file contains the directory that we are currently in. It is used to establish import paths and such.

In our project, our program is contained entirely within the web.go program. Open this with a text editor to take a look inside:

nano web.go

In the top of the program, you'll see the import statements for the libraries that I mentioned above:

package main

import (
    "os"
    "fmt"
    "net/http"
    _ "github.com/lib/pq"
    "database/sql"
)

We hook into our database with these lines. See how the os.Getenv("DATABASE_URL") line assigns an internal variable to the environmental variable. This is how you will connect to the database with your own applications.

dokku_db := os.Getenv("DATABASE_URL")

db, err = sql.Open("postgres", dokku_db)
if err != nil {
        fmt.Printf("sql.Open error: %v\n", err)
        return
}
defer db.Close()

The rest of the file involves creating a table and writing some initial data to it. When you are finished, close the file.

Deploying your Go Application to Dokku


Since we obtained this project from GitHub, it is already under version control. We need to set up our Dokku droplet as a git remote for our project so that git can push it effectively.

This is done through a command like this:

git remote add remote_name dokku@your_domain.com:app_name

In this command, the remote_name can be anything you choose. It is simply a label to reference the remote Dokku machine. In most cases, "dokku" or "production" would be appropriate names.

The app_name parameter must match the name you selected for your database. If your application did not use a backend database, this would be the place where you would be selecting the name you'd be using to access your application within the URL.

Now that our application is ready and knows about our Dokku server, we can deploy simply by pushing it to the remote server, where the Dokku program will take over and configure the application environment:

git push remote_name master

You should see some output that looks something like this:

-----> app_name linked to postgresql/app_name database
-----> Deploying here ...
-----> Cleaning up ...
=====> Application deployed:
       http://app_name.your_domain.com

To dokku@your_domain.com:app_name
 * [new branch]      master -> master
 

If you visit that URL in your web browser, you should see the output of the program:

Dokku Go application example

Conclusion


You should now have a sample Go application launched by your Dokku droplet. While the example program is quite messy, it demonstrates some of the steps required to get your Go application to play nicely with a web deployment application like Dokku. The deployment itself is very easy and happens quickly.

By Justin Ellingwood

3 Comments

Creative Commons License