Getting Started on Akkeris with Ruby

Table of Contents

Introduction

In this tutorial you will deploy a Ruby app using the Rails web framework in minutes.

Hang on after the tutorial for a few minutes to find out how Akkeris works and other information so you can make the most out of Akkeris and its dev tooling.

Before we proceed make sure you're comfortable with Terminal concepts and have access to a terminal on Windows, macOS, or Linux. If you need to brush up on your terminal skills read through this terminal guide first.

You'll also need to ensure you have (at a bare minimum) node.js (8+) installed (for the CLI system). Be sure to check our prerequisites to ensure you can make the most out of Akkeris.

Set up

In this step you will install the Akkeris Command Line Interface (CLI), or AppKit as its sometimes referred to. You will use the CLI to manage and scale your applications, to provision add-ons, to install plugins from other engineers on your teams, to view the logs of your application as it runs on Akkeris, to pull logs from legacy apps, as well as to help run your application locally.

Install Akkeris:

npm -g install akkeris

Note, if you receive an error about insufficient permissions you may need to run sudo npm -g install akkeris instead.

Then type:

aka

Hi! It looks like you might be new here. Lets take a second
to get started, you will need your akkeris auth and apps host
in addition to your login and password.

Akkeris Auth Host (auth.example.io): auth.example.io
Akkeris Apps Host (apps.example.io): apps.example.io
Profile updated!
Username: first.lastname
Password: ******
Logging you in ...  ✓

Note that after you login you may see a list of commands available.

Create an app on Akkeris

In this step, you will prepare a simple application that can be deployed.

aka apps:create -s voltron -o test
Creating app ⬢ digestion1077-voltron ...  ✓ 
https://digestion1077-voltron.alamoapp.akkeris.io/

This will create a new app with a randomly generated name digestion1077 in the spacevoltron, assigned to our testing organization. You can pass a parameter to specify your own app name.

Note: Your application name may vary, keep a note of your randomly generated app name as you'll need it later, you can also create an app with a specific name by passing it in as an arguement to the command above.

Create your Rails app

Create a simple app by following this Getting Started with Rails guide at least through the end of section 4 "Hello Rails," but you can stop before section 5 "Getting Up and Running."

At this point you should have a simple Rails app that you can spin up with

aka apps:create -s voltron -o test
Creating app ⬢ digestion1077-voltron ...  ✓ 
https://digestion1077-voltron.alamoapp.example.io/

bin/rails server

and then navigate to the home page at http://localhost:3000/ to see "Hello, Rails!"

Note: For your app to run in the Docker container, you may need to uncomment the gem 'mini_racer' line in your Gemfile.

Add a Dockerfile to your app

To deploy to Akkeris a special file called a Dockerfile is needed. It is auto detected by Akkeris and tells it how to start your application, and how to build your application.

Create a new file in the project root directory named Dockerfile (case sensitive) and copy this into it

FROM ruby
WORKDIR /usr/src/app
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .
CMD bin/startup

Now let's create the bin/startup file referenced on the last line of our Dockerfile and give it the following contents.

#!/usr/bin/env bash
bin/rails server --binding 0.0.0.0 --port $PORT

Then make that file executable.

chmod +x bin/startup

If it does not appear give it a few seconds to start up.

Upload your app repo to GitHub

Most applications are deployed via a source control repository such as GitHub. This is called an auto build. In this section we'll learn how we can automatically attach our app to Github and deploy code as commits are made.

Create a new github repo

In this example you'll need to create a new repo on GitHub, you can create it under OC Tanner or under your personal account. You can do this at https://github.com/new. Do not initialize the repository with a README, do not add a .gitignore, and do not add a license.

In your terminal, from the directory containing your new Rails app, commit your code if you haven't already.

git add .

git commit -m "first commit"

Then add your new GitHub repo as the remote and push up your code.

git remote add origin https://github.com/[org]/[repo].git
```shell
git push -u origin master

Attach Github to your app

Next, set your app to automatically deploy anytime there's a change on the repo:

aka repo:set https://github.com/[org]/[repo] --token [token] \
  --username [github username] --app digestion1077-voltron

Note, you can use the token you generated when you setup your Github CLI.

Trigger a new deploy

Now any change to your repo will create a new build. So we can trigger a new build by committing our new Dockerfile and pushing it up to GitHub.

git add Dockerfile

git commit -a -m 'Create Dockerfile'

git push

To watch your logs, run:

aka logs --tail -a digestion1077-voltron

Note the --tail in the command above means to tail the logs, it keeps showing new logs until you press CTRL+C to stop it. Once the logs show Example app listening 9000 its up and running, remember to press CTRL+C to stop watching the logs.

You've successfully attached and deployed your code from Github! To see your application run:

aka apps:open -a digestion1077-voltron

If it does not appear give it a few seconds to start up.

Scale the app

Right now, your app is running on a single dyno. Think of a dyno as a lightweight container (in fact in the docker world is it a container) that runs the specified command in your Dockerfile.

You can now check how many dynos are running using the ps command:

aka ps -a digestion1077-voltron
=== web (scout): (from docker) (1)
web.2885060676-76szt: up 10/27/2017, 2:36:42 PM

By default, your app is deployed on a small dyno (a scout size). And only one dyno type "web". Dyno types specify what special considerations your process may need when it starts, the dyno type "web" indicates it should be given a URL on the web, it also tells alamo to direct its web traffic to the port specified with the$PORTenvironment variable in your configuration. You should listen to the$PORTenvironment configuration variable to receive web traffic and respond to it.

You can also create new dyno types or scale existing dyno types using aka ps:update. For example, you can change the amount of servers your application is running on to zero by doing:

aka ps:update -q 0 -a digestion1077-voltron
...

If you then open up your app using aka apps:open -a digestion1077-voltron you will get an error message since the application is no longer running.

You can scale it back up again by running:

aka ps:update -q 1 -a digestion1077-voltron

If you need to run background processes you can create a new process type using aka ps:create worker -c [command] -a digestion1077-voltron. This will create a new background process called worker that can be scaled independently of your web dyno. It will receive the same code and deployments and configuration but does not need to listen to web traffic or respond on a port. It can independently run background processes as needed.

Define config vars

Akkeris allows you to store configuration information outside of your code. Storing data such as encryption keys or API URL's as config vars allows you to have one code base and branch run on multiple environments and gives you a space where confidential information can be stored and retrieved.

At runtime, config vars are exposed as environment variables to the application (e.g., process.env.MY_VARIABLE). For example, to set a config var TIMES=2 on Akkeris, execute the following:

aka config:set TIMES=2 -a digestion1077-voltron

=== digestion1077-voltron Config Vars
 PORT                                 9000
 TIMES                                2

View the config vars that are set using aka config:

aka config -a digestion1077-voltron

=== digestion1077-voltron Config Vars
 PORT                                 9000
 TIMES                                2

Now that the config var is added open your app using aka open -a digestion1077-voltron and change the path to /times, you should see the value 0 1.

Provision add-ons

Add-ons are third-party services or shared credentials that provide out of the box additional functionality for your application, from databases, persistence, s3 buckets through logging to monitoring and more. You can view a list of all of the services you can attach to your application as an addon using:

aka services

You can then view plans for each service by running aka services:plan. For example, to view all of the plans for a postgresql database you can run:

aka services:plans akkeris-postgresql

You can then provision addons from a service plan by running aka addons:create [service]:[plan], you can provision a small database by running:

aka addons:create akkeris-postgresql:standard-0 -a digestion1077-voltron

Note that the connection information for the service provisioned are added as config vars. You can view the new config vars created by the provisioned database by running aka config -a digestion1077-voltron.

In this next example we'll show how to provision papertrail as a service. Note that all services for Akkeris are provisioned via addons.

Provisioning Papertrail Services

By default akkeris does not store any of your logs from your application or http requests. However, it makes the full log stream available as a service - this is called a log drain. A log drain is a syslog or http end point where your logs will be forwarded to by alamo.

In this step we'll provision an addon that will add a log drain to your app, Papertrail. Papertrail allows searching, storing and alerting based on logs online a https://papertrailapp.com.

Provision the papertrail logging add-on:

aka addons:create papertrail:basic -a digestion1077-voltron

=== Addon papertrail-camera-5168 Provisioned
=== papertrail-camera-5168 (f5a86fae-b54f-481f-a8c8-006942541ee8)

...

The add-on is now deployed and configured for your application. You can list add-ons that are installed for your app using:

aka addons -a digestion1077-voltron

If you visit https://papertrailapp.com/systems/digestion1077-voltron/events you can see the logs from your application, it may take a second or two for them to appear. The interface also allows you to setup searches and alerts.

Next Steps

You now know how to deploy an app, change its configuration, view logs, scale, and create add-ons from services.

Here’s some recommended reading. The first, an article, will give you a firmer understanding of the basics. The others may interest you in how you can best take advantage of Akkeris.

  • Read How Akkeris Works for more a technical overview you'll encounter while writing, deploying, running and managing applications on Akkeris.
  • Read Best Practices and Guidelines for more information on how you can take full advantage of Akkeris and other developer workflow tips and tricks.
  • Read Extending Akkeris to learn how you can use the Platform Apps API, shared credentials and create custom addons to extend its funtionality and introduce customized workflows or features.

Have Questions?

  • Join our slack channel at #akkeris (akkeris.slack.com)

results matching ""

    No results matching ""