A Swift Web Framework and HTTP Server
Summary
Kitura is a web framework and web server that is created for web services written in Swift.
Table of Contents
Features
- URL routing (GET, POST, PUT, DELETE)
- URL parameters
- Static file serving
- FastCGI support
- JSON parsing
- Pluggable middleware
Swift version
Version 0.26
of Kitura requires the DEVELOPMENT-SNAPSHOT-2016-07-25-a
version of Swift 3 trunk (master). You can download this version at swift.org. Kitura is unlikely to compile with any other version of Swift.
Installation
macOS
- Install Homebrew (if you don't already have it installed):
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
- Install the necessary dependencies:
$ brew install curl
-
Download and install Xcode 8 beta 6.
-
Download and install the required Swift version from
swift.org
.
During installation if you are using the package installer make sure to select "all users" for the installation path in order for the correct toolchain version to be available for use with the terminal.
After installation, make sure you update your PATH
environment variable as described in the swift.org
installation instructions (e.g. export PATH=/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin:$PATH
)
- Select the Xcode beta as your active developer directory.
$ sudo xcode-select -s /Applications/Xcode-beta.app/Contents/Developer/
Now you are ready to develop your first Kitura app. Check Kitura-Sample or see Getting Started.
Ubuntu Linux
Kitura is tested on Ubuntu 14.04 LTS and Ubuntu 15.10.
- Install the following system linux libraries:
$ sudo apt-get install autoconf libtool libcurl4-openssl-dev libbsd-dev libblocksruntime-dev
- Install the required Swift version from
swift.org
.
After installing it (i.e. extracting the .tar.gz
file), make sure you update your PATH
environment variable so that it includes the extracted tools: export PATH=/<path to uncompress tar contents>/usr/bin:$PATH
.
- Clone, build and install the libdispatch library.
The complete instructions for building and installing this library are shown here. For convenience, the command to compile is:
$ export SWIFT_HOME=<path-to-swift-toolchain>
$ git clone --recursive -b experimental/foundation https://github.com/apple/swift-corelibs-libdispatch.git && cd swift-corelibs-libdispatch && sh ./autogen.sh && CFLAGS=-fuse-ld=gold ./configure --with-swift-toolchain=$SWIFT_HOME/usr --prefix=$SWIFT_HOME/usr && make && make install
Now you are ready to develop your first Kitura app. Check Kitura-Sample or see Getting Started.
Docker
-
Install Docker on your development system.
-
Pull down the kitura-ubuntu image from Docker Hub:
$ docker pull ibmcom/kitura-ubuntu:latest
- Create a Docker container using the
kitura-ubuntu
image you just downloaded and forward port 8090 on host to the container:
$ docker run -i -p 8090:8090 -t ibmcom/kitura-ubuntu:latest /bin/bash
- From within the Docker container, execute the
clone_build_kitura.sh
script to build the Kitura-Starter-Bluemix sample project:
# /root/clone_build_kitura.sh
The last two output lines from executing the clone_build_kitura.sh
script should be similar to:
Linking .build/debug/Kitura-Starter-Bluemix
>> Build for Kitura-Starter-Bluemix completed (see above for results).
- You can now run the Kitura-Starter-Bluemix executable inside the Docker container:
# /root/start_kitura_sample.sh
You should see an output message that contains the string Listening on port 8090
.
Vagrant
-
Install VirtualBox.
-
Install Vagrant.
-
From the root of the Kitura folder containing the
vagrantfile
, create and configure a guest machine:
$ vagrant up
- SSH into the Vagrant machine:
$ vagrant ssh
- As needed for development, edit the
vagrantfile
to setup Synced Folders to share files between your host and guest machine.
Now you are ready to develop your first Kitura app. Check Kitura-Sample or see Getting Started.
Getting Started
Let's develop your first Kitura web application!
- First, create a new project directory.
$ mkdir myFirstProject
- Next, create a new Swift project using the Swift Package Manager.
$ cd myFirstProject
$ swift package init --type executable
Now your directory structure under myFirstProject should look like this:
myFirstProject ├── Package.swift ├── Sources │ └── main.swift └── Tests └── empty
Note: For more information on the Swift Package Manager, go here.
- In
Package.swift
, add Kitura as a dependency for your project.
import PackageDescription
let package = Package(
name: "myFirstProject",
dependencies: [
.Package(url: "https://github.com/IBM-Swift/Kitura.git", majorVersion: 0, minor: 26)
])
- In
Sources/main.swift
, import the Kitura module.
import Kitura
- Add a router and a path:
let router = Router()
router.get("/") {
request, response, next in
response.send("Hello, World!")
next()
}
- Add an HTTP server and start the Kitura framework.
Kitura.addHTTPServer(onPort: 8090, with: router)
Kitura.run()
- Your
Sources/main.swift
file should now look like this.
import Kitura
let router = Router()
router.get("/") {
request, response, next in
response.send("Hello, World!")
next()
}
Kitura.addHTTPServer(onPort: 8090, with: router)
Kitura.run()
-
Optionally, add logging.
In the code example above, no messages from Kitura will logged. You may want to add a logger to help diagnose any problems that occur.
Add a HeliumLogger dependency to
Package.swift
.import PackageDescription let package = Package( name: "myFirstProject", dependencies: [ .Package(url: "https://github.com/IBM-Swift/Kitura.git", majorVersion: 0, minor: 26), .Package(url: "https://github.com/IBM-Swift/HeliumLogger", majorVersion: 0, minor: 14), ])
Enable HeliumLogger in
Sources/main.swift
.import HeliumLogger HeliumLogger.use()
Here is the finished
Sources/main.swift
file.import Kitura import HeliumLogger HeliumLogger.use() let router = Router() router.get("/") { request, response, next in response.send("Hello, World!") next() } Kitura.addHTTPServer(onPort: 8090, with: router) Kitura.run()
-
Compile your application:
- macOS:
$ swift build
- Linux:
$ swift build -Xcc -fblocks
Or copy our Makefile and build scripts to your project directory and run make build
. You may want to customize this Makefile and use it for building, testing and running your application. For example, you can clean your build directory, refetch all the dependencies, build, test and run your application by running make clean refetch test run
.
- Now run your new web application:
$ .build/debug/myFirstProject
- Open your browser at http://localhost:8090
Contributing to Kitura
All improvements to Kitura are very welcome! Here's how to get started with developing Kitura itself.
- Clone this repository.
$ git clone https://github.com/IBM-Swift/Kitura
- Build and run tests.
$ make test
Notes
-
Homebrew by default installs libraries to
/usr/local
, if yours is different, change the path to find the curl library, inPackage-Builder/build/Makefile
:SWIFTC_FLAGS = -Xswiftc -I/usr/local/include LINKER_FLAGS = -Xlinker -L/usr/local/lib
You can find more info on contributing to Kitura in our contributing guidelines.
Community
We love to talk server-side Swift, and Kitura. Join our chat channel on Gitter to meet the team!