< Cocoa Dev Central

Swift + Kitura on DigitalOcean

Kitura is a web framework and server from IBM for Swift. It offers native speed, type safety, and multi-threaded request handling. Installation on OS X is very straightforward, but you may not have an OS X-based server to deploy to. DigitalOcean makes it easy to deploy very fast, affordable Linux servers. The entry-level tier is $5 per month.

There's nothing especially difficult about getting Swift/Kitura running on a provider like DigitalOcean, but there are a lot of steps and some of the documentation assumes a level of experience that not everyone will have. It's easy to get lost. This glues together details from a few places to (hopefully) let you setup everything in a single go.

This guide should theoretically work for any Ubuntu 15.10 x64 system, but there are more specific steps for DigitalOcean. The whole setup should take under an hour, maybe as little as 20 minutes. You need to understand basic command line usage.

Note: This guide is not affiliated with or endorsed by IBM, Apple, or DigitalOcean. This is just to help people get started. The setup steps provided are derived from these installation guides:

Updated on February 24, 2016 to reflect changes in the official Kitura installation.

Create a Droplet

First, create a DigitalOcean account. DigitalOcean calls individual servers "droplets". Once configured, they are generally available in under a minute. Configure a droplet with the following options:

Distribution : Ubuntu 15.10 x64

: Ubuntu 15.10 x64 Size : $5/mo (you can change it later)

: $5/mo (you can change it later) Region : Whichever you like

: Whichever you like SSH key : It's better if you add your key, but it's not required (SSH key tutorial). If you don't, DigitalOcean will email you the root password.

: It's better if you add your key, but it's not required (SSH key tutorial). If you don't, DigitalOcean will email you the root password. Hostname: anything you like. It can be something like "swift-kitura"

Click the Create button, and wait about a minute. Once the droplet is created, you should see it listed on your DigitalOcean account page. Copy the IP address for the droplet and open Terminal. Type:

ssh <ip address goes here> -l root

If you added an SSH key, you'll be asked to enter your passphrase. If you didn't provide an SSH key, look for the password in your email, and enter it on the command line (you'll be asked to change it the first time you login).

When you login, you should see something like:

Welcome to Ubuntu 15.10 (GNU/Linux 4.2.0-27-generic x86_64) root@swift-kitura:~#

User

Create a user. This can be the same as your local user on your personal machine:

adduser <user name>

Provide a password. You can leave everything else blank, though you may want to provide a full name. Give the new account sudo access so you can make changes to the system with this account:

gpasswd -a <user name> sudo

To make things a bit more secure and avoid making a breaking change to the server by mistake, you can disconnect from the droplet, and log back in with the newly-created account so that you're not entering commands as root.

When you're logged in as your normal user account and need to make changes that require adminstrator priveleges, you can use the sudo command in front of any other command.

Firewall

Firewalls can get really sophisticated, but for our purposes, we'll just make sure things are locked down to basic services. DigitalOcean has a fantastic tutorial on UFW, but here's an ultra-simplified version.

Default to disallowing incoming traffic, and allowing outgoing traffic. Enter these on the command line:

sudo ufw default deny incoming sudo ufw default allow outgoing

Allow ssh, http, and https:

sudo ufw allow ssh sudo ufw allow http sudo ufw allow https

Allow port 8090, which is the default port for Kitura:

sudo ufw allow 8090

Enable the firewall. It is absolutely critical that you allowed ssh before doing this, otherwise you'll be locked out of the droplet:

sudo ufw enable

Swift

Install Required Packages

There are a number of packages Swift and Kitura need to function. Ubuntu Linux uses the apt-get install <package> command to install packages. We'll install the packages in two phases.

For the first phase, we want these packages:

git

clang

libicu-dev

curl

Run this command, and wait a while:

sudo apt-get install git clang libicu-dev curl

Install Swift

Go to http://swift.org/download/ and look for the latest development snapshot of Swift for Ubuntu 15.10. Copy the development snapshot URL. Use the following commands to go to your home directory and download the Swift snapshot to the server:

cd ~ curl -O <paste development snapshot URL here>

Do an ls to see the downloaded file. It will look something like this:

swift-DEVELOPMENT-SNAPSHOT-2016-02-08-a-ubuntu15.10.tar.gz

Now unarchive it:

tar xzvf <name of downloaded file>

Do an ls and it should look similar to this:

swift-DEVELOPMENT-SNAPSHOT-2016-02-08-a-ubuntu15.10 swift-DEVELOPMENT-SNAPSHOT-2016-02-08-a-ubuntu15.10.tar.gz

Create a symbolic link (alias) called 'swift' that points to the directory of the unarchived snapshot:

ln -s <name of unarchived directory> swift

Whenever you get a new version of Swift for the server, you should remove and remake this link so it's easy to reference.

Edit .bashrc

To make sure that you can build Swift and Kitura projects from anywhere, edit the file in your home directory called .bashrc . I use the vi editor, but you can use nano (nano tutorial) or any editor. Both take time to learn, so you can also just download the file over SFTP, change it, and upload it.

At the very bottom of .bashrc, add these two lines to the file (don't just type them):

export PATH=$HOME/swift/usr/bin:"${PATH}" export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

The path uses the symbolic link you created, so it should always work, even after you update. Run this command to reload the file:

source .bashrc

Kitura

Packages Required by Kitura

To install Kitura, we need the following packages:

autoconf

libtool

pkg-config

libhttp-parser-dev

libcurl4-openssl-dev

libhiredis-dev

libblocksruntime-dev

libkqueue-dev

libpthread-workqueue-dev

libbsd-dev

Run this command, and wait while everything installs. The slashes are just to break the command up into multiple lines so it fits here. It doesn't change the result, and you can leave it out entirely:

sudo apt-get install autoconf libtool pkg-config libhttp-parser-dev \ libcurl4-openssl-dev libhiredis-dev libblocksruntime-dev \ libkqueue-dev libpthread-workqueue-dev libbsd-dev

libdispatch Patch and PCRE

There are two things we need to install manually, not using apt-get:

A patch for libdispatch (referenced by the official Kitura instructions)

PCRE, the Perl Compatible Regular Expressions library

The libdispatch patch cannot be installed using apt-get. The PCRE library can be installed with apt-get, but the official instructions suggest installing it manually, and I haven't tried it with the package version yet. So for now, let's follow the official instructions.

First, grab the libdispatch patch with git:

git clone https://github.com/apple/swift-corelibs-libdispatch.git

Now, build the patch and install it. Some of these steps may take a while. Replace " <path to swift symlink> " with the location of the symlink you made earlier:

cd swift-corelibs-libdispatch sh ./autogen.sh ./configure --with-swift-toolchain=<path to swift symlink>/usr --prefix=<path to swift symlink>/usr make make install

Now, go back to your home directory, download PCRE and unarchive it:

cd ~ curl -O "http://ftp.exim.org/pub/pcre/pcre2-10.20.tar.gz" tar zxvf pcre2-10.20.tar.gz

Build and install PCRE. Again, this may take a while:

cd pcre2-10.20 ./configure make sudo make install

Install Kitura

Return to your home directory and clone Kitura with git:

cd ~ git clone https://github.com/IBM-Swift/Kitura.git cd Kitura

Build Kitura with the make command:

make

Launch the example server app:

.build/debug/KituraSample

If everything worked, you should be able to load the page in your browser by typing in the droplet's IP address, with a port of 8090. For example: http://198.51.100.1:8090

Optional: Droplet Snapshot

At this point, you can create a snapshot of the Droplet. This is helpful in at least two scenarios:

You want to create another server setup the same way without install everything again

The server configuration is changed and Kitura won't run

If you have a snapshot, you can always restore from an image. To create a snapshot, first use this command to shutdown the droplet:

sudo poweroff

Then go into your DigitalOcean account, click on the droplet, and choose "Snapshots" from the sidebar. It will take several minutes to capture the snapshot, and then the droplet will automatically come back online.

Next Steps