Getting started with Kitura on Heroku

Kitura is a web framework created by IBM. It is a really simple framework with more than a passing similarity to frameworks such as Sinatra, Express, Lumen and Flask. It is written in Swift so there are some big draws towards using it as you can start to consider writing both your client code (assuming you are building for iOS and OS X) and server side code in the same language.

This isn’t the first time that we’ve started to see this kind of thing. In the land of browser based applications you’re able to write Javascript in the browser and on the server thanks to tools like NodeJS. On Android thanks to the use of Java you’re able to share code with your backend and your apps (There’s a big win here as the Java ecosystem is absolutely huge).

Personally I started to get really interested in Swift as a server side language with the release of Swift 3 which bundled in the Swift Package Manager (SPM) and a native port of Foundation. For those of you who aren’t aware Foundation is one of the key frameworks that brought a lot to Objective-C and Swift. Since the original Foundation library was written in Objective-C it was not available to Swift on Linux, but there has now been an effort to re-implement Foundation natively in Swift and it is starting to bear fruit.

Setup

Swift

For the sake of this write up I’ll assume that you are running on OS X in which case you will want to pop over to the App Store and grab Xcode 8. If you aren’t a fan of the App Store it is also available as a direct download through the Apple Developer Portal.

Getting things setup on Linux is a little more involved but there are some installation steps outlined for you on the Swift website.

Once you’ve got everything installed you will be able to run:

$ swift --version

This should show you what version of Swift you currently have installed. For this guide I’m assuming you are running Swift 3.0.

Heroku

Next up you will want to grab the Heroku Toolbelt. This will setup everything for you on your machine, I’ll assume that you have created an account with Heroku and have logged in using the toolbelt at this point. Don’t worry you won’t need to create any apps just yet.

Build

Now you’ve got your development environment setup we can get to the fun bit of actually building our application.

First off you will want to create the project structure for your application. Swift Package Manager (SPM) helps you here:

$ mkdir myFirstKituraApp
$ cd myFirstKituraApp
$ swift package init --type executable

This will setup the following standard SPM folder structure for you:

.
├── .gitignore
├── Package.swift
├── Packages
├── Sources
│ └── main.swift
└── Tests

Xcode

At this point if you are running OS X and Xcode then you can generate an xcodeproj file so that you can get going. If you want to do this you will need to run:

$ swift package generate-xcodeproj
Watchout! You will need to run this when you update your Package.swift file dependencies and fetch them to ensure that you have the latest dependencies in your project.

Dependencies

First we need to grab the Kitura dependencies we are going to be using. Open up Package.swift and make sure that it looks like the following:

How the Package.swift file should look for this project

Once you’ve saved that you’ll need to run:

$ swift package fetch

You could build the project at this point if you wished but a fetch will suffice for now.

The App

Now to the meat of the application. Open up Sources/main.swift and add the following:

All of the greatest starts are a Hello world

The port resolution logic involves a bit more as we want to listen out for the PORT environment variable. There will be some more about this in the Deploy section of this guide.

Version Control

Heroku requires that your app is managed by git before you deploy it. So we will need to get this all under version control:

$ git init
$ git add .
$ git commit -m "Initial commit"

Once you are done you can try this out on the command line or by running it from Xcode. To run this app from the command line you will need to run:

$ swift build

This will build and package your application for you. Once the process is complete you can run it with:

$ .build/debug/myFirstKituraProject

Now point your browser at http://localhost:8080 and you should see something roughly like the following:

If you can see this then your app is running correctly locally

Deployment

Now let’s get this project sent off to Heroku so that you can share your creation with the world.

First create a new file called Procfile in the root of your project and add the following to it.

The Procfile that instructs Heroku to run your application

Next up you will want to run the following command to create a new Swift application:

$ heroku create --buildpack https://github.com/kylef/heroku-buildpack-swift.git

This command uses a custom buildpack that includes Swift 3.0 (the current stable version). You might be interested in taking a look at the repository so that you can see what’s involved in creating a custom buildpack.

Once this command has run you now should have an application on your account. Don’t worry if you are running this on the free tier that should be more than enough to run this app.

Now to push your application:

$ git push heroku master

This command will take a small amount of time while the slug is built for your application. It needs to fetch your dependencies and compile it for the Ubuntu Linux OS running your slug.

Once it’s done to open your new application in your browser run:

$ heroku open

Ports

In your application we had to add code to handle the PORT environment variable. This needs to be done as this is how Heroku tells our application which port it needs to listen on to receive requests from the web. If you don’t do this then the application will attempt to listen on port 8080 which is not available.

That’s it you’re running your new application on Heroku. Go and build something great.