Buffalo-Ocean Plugin Walkthrough

Create DigitalOcean Account (Referral Link)

Buffalo-Ocean Repo


(Paraphrased for clarity)

Today we’re going to be taking a look at the Buffalo-Ocean plugin used for deploying your Buffalo web application to the Digital Ocean hosting service. You can install it with:

go get -u github.com/wolves/buffalo-ocean

There’s also a link to the repository on the plugins page of the gobuffalo.io website.

The first thing we’re going to take a look at is a couple of the flags that are available to you with the setup step.

$ buffalo ocean setup -h

A brief description of your command

  buffalo-ocean ocean setup [flags]

  setup, s

  -a, --app-name string      The name for the application
  -b, --branch string        Branch to use for deployment (default "master")
  -e, --environment string   Setting for the GO_ENV variable (default "production")
  -h, --help                 help for setup
  -k, --key string           API Key for the service you are deploying to
      --skip-envs            Skip the environment variable settup step
      --skip-ssl             Skip the SSL setup step
  -t, --tag string           Tag to use for deployment. Overrides branch.

The setup step is the first step that you’ll need to run if you’ve never used the Buffalo-Ocean plugin. The main flag you need to be concerned with here is --app-name. This is used to label your docker-machine, which is what Buffalo-Ocean uses to provision a new droplet on DigitalOcean, so it is required.

We’re also going to be skipping the SSL step with --skip-ssl for the sake of the demonstration. One note, in your project, if you do choose to --skip-ssl you’re going to need to go into your actions/app.go file and comment out the force SSL middleware.

// Automatically redirect to SSL
    SSLRedirect:     ENV == "production",
    SSLProxyHeaders: map[string]string{"X-Forwarded-Proto": "https"},

So the application we’re going to be deploying today is a basic generated Buffalo application. The one thing that has been added to it, for the demonstration, is a “pets” scaffolding to show the migrations working in a setup or deploy.

Going back to the plugin in our application directory, we’re going to run buffalo ocean setup and pass in an --app-name flag; we’ll use “example” as the name and we’re going to --skip-ssl.

There’s also a --key flag available. This is for your DigitalOcean API key. I already have one, but I’m skipping this flag in order to show you what the prompt is and how to set one up for yourself. If you’ve never set up an API key on DigitalOcean, the prompt gives you the url and their website will direct you from there. So we will run:

$ buffalo ocean setup --app-name example --skip-ssl

==> PROVISIONING SERVER: example-production.

==> Creating docker machine: example-production
Enter your write enabled Digital Ocean API KEY or create one with the link below.

"Please enter your DigitalOcean Token:"

Immediately, it’s going to ask us for that key. It provides you with the url that you’ll need to visit to generate a key. You can enter whatever name you want to call the key in the website’s modal as the label for that API token. I already have one setup so I will be using my token for the demo and then creating a new one later.

Once you’ve pasted it in or typed it out, if you’re into that kind of thing, you can hit enter and it’s going to begin to provision your docker-machine and DigitalOcean droplet. At this point it’ll take a little bit of time to run and then you’ll be prompted to enter your project repository information.

The setup step is only required the first time. It’s much quicker once you’ve done the initial setup and you can just execute deploy.

==> Creating Deploy Key
Enter file in which to save the key (/root/.ssh/id_rsa):

"Please add this to your project's deploy keys on Github or Gitlab:"

Reading package lists...
Building dependency tree...
Reading state information...
git is already the newest version (1:2.7.4-0ubuntu1.3).
The following package was automatically installed and is no longer required:
Use 'apt autoremove' to remove it.
0 upgraded, 0 newly installed, 0 to remove and 4 not upgraded.

"Please enter the repo to deploy from (Example: git@github.com:username/project.git):"

Once we reach this step, the Buffalo-Ocean plugin provides us with our ssh key, which we’ll need to apply to our repository of the project that we’re deploying. To do this, go to the project’s Github repository. Then, to enter the ssh key, go to Settings > Deploy Keys > Add a Deploy Key. Paste in your copied ssh key and click “Add Key”.

While you are in your repo, go over and copy the ssh link for the project repo so that you can come back and provide it to the Buffalo-Ocean plugin. This way it knows which project you are deploying. When you hit enter here, it’s going to begin cloning the project and setting up the docker containers which takes a bit of time.

If you chose to not run the --skip-envs flag, this is the point at which it prompts you to enter your, space separated, environment variables.

==> Cloning Project
# github.com:22 SSH-2.0-libssh_0.7.0
# github.com:22 SSH-2.0-libssh_0.7.0
# github.com:22 SSH-2.0-libssh_0.7.0
Cloning into 'buffaloproject'...
Warning: Permanently added the RSA host key for IP address '' to the list of known hosts.

"Enter the ENV variables for your project with a space between each: (eg. SAMPLE=test FOO=bar)"


We will setup an environment variable just for the demo and hit enter to kickoff the project setup. This will take a bit of time and is where you go get a bowl popcorn, soda or an adult beverage if that’s your preference and sit back while it runs.

Once this is complete your machine is setup and can be previewed at the IP address that the plugin provides:



ssh root@ -i ~/.docker/machine/machines/example-production/id_rsa

Now that we have our application deployed, we can make sure that the docker machine is running.

$ docker-machine ls

You should see something like “example-production”. Using that information we can go and verify the environment variables, which were set in the setup step. To do that, just ssh into the docker machine that was created.

$ docker-machine ssh example-production

From here, within the docker-machine/droplet you can double check to make sure that your containers are running.

$ docker container ls

You should see that the plugin created a buffaloweb and a buffalodb container for you on your DigitalOcean droplet. To check your environment variables, which should be set in the buffaloweb container, go into the docker container and echo out the variables you set to verify your environment variables have been set.

$ docker container exec -it buffaloweb sh
$ echo $ENV_NAME

The next thing we’re going to go through is the deploy step. If you’ve already run the initial setup step on a project, which is something you only have to do the first time, you can run deploy. It’s much faster and it updates your site with any of the changes that you’ve made to your project from your Github repository. It pulls them into your container and rebuilds the container with those changes. So for the sake of the demo, we will just go in and type:

$ buffalo generate resource user name email

That’s going to create a new standard user resource with a name and email field in the Buffalo project. You’ll want to commit that and push it to Github so the deploy step will be able to access the changes.

$ git add .
$ git commit -m "Adding users"
$ git push

Let’s take a look at some of the flags available to the deploy step in Buffalo-Ocean:

$ buffalo ocean deploy -h

Deploy to DigitalOcean using docker

  buffalo-ocean ocean deploy [flags]

  deploy, d

  -a, --app-name string      The name for the application
  -b, --branch string        Branch to use for deployment (default "master")
  -e, --environment string   Setting for the GO_ENV variable (default "production")
  -h, --help                 help for deploy
  -t, --tag string           Tag to use for deployment. Overrides banch.

The primary one you’re going to be focused on here is the --app-name flag. You want to make sure that you use the same exact --app-name that was used during your setup step so that the plugin recognizes what machine to run the code on.

$ buffalo ocean deploy --app-name example

This will pull down your code from your repository, begin deploying the new project and rebuild your container. It will take much less time than the setup step did.

Once you’ve run the deploy step, you should be able to go over to our running application at the IP address provided, refresh it, and see your changes. Also the deploy step is non-destructive to the database container.

A couple points of note:

Thanks everyone for taking the time to look at Buffalo-Ocean with me today. If you have any questions, feel free to email me or go on the Github repo. Any issues or any suggestions are always welcome.


comments powered by Disqus