A Swift Web Framework and HTTP Server
Kitura is a web framework and web server that is created for web services written in Swift.
- URL routing (GET, POST, PUT, DELETE)
- URL parameters
- Static file serving
- JSON parsing
- Pluggable middleware
The latest version of Kitura works with the DEVELOPMENT-SNAPSHOT-2016-03-01-a version of the Swift binaries. You can download this version of the Swift binaries by following this link.
-
Install Docker on your development system and start a Docker session/terminal.
-
From the Docker session, 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:
docker run -i -t ibmcom/kitura-ubuntu:latest /bin/bash
- From within the Docker container, execute the
clone_build_test_kitura.sh
script to build Kitura and execute the test cases:
/root/clone_build_test_kitura.sh
The last output line from executing the clone_build_test_kitura.sh
script should be similar to:
>> Finished execution of tests for Kitura (see above for results).
- You can now run the KituraSample executable inside the Docker container:
/root/start_kitura_sample.sh
You should see a message that says "Listening on port 8090".
-
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
- From the Vagrant shell, run the sample program:
Kitura/.build/debug/KituraSample
. You should see a message that says "Listening on port 8090".
- As needed for development, edit the
vagrantfile
to setup Synced Folders to share files between your host and guest machine.
- 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 http-parser curl hiredis
- Download and install the supported Swift compiler.
After installing it, make sure you update your PATH environment variable as described in the installation instructions (e.g. export PATH=/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin:$PATH)
-
Clone this repository,
develop
branchgit clone -b develop https://github.com/IBM-Swift/Kitura
-
build and run Kitura Sample
make run
You should see a message that says "Listening on port 8090".
- Homebrew by default installs libraries to
/usr/local
, if yours is different, change the path to find curl and http-parser libraries, in Kitura-CI/build/Makefile:
SWIFTC_FLAGS = -Xswiftc -I/usr/local/include
LINKER_FLAGS = -Xlinker -L/usr/local/lib
- The result executable is located in
.build/debug
folder in the cloned repository:./.build/debug/KituraSample
- Install the following system linux libraries:
sudo apt-get install libhttp-parser-dev libcurl4-openssl-dev libhiredis-dev
- Install the supported Swift compiler for Linux.
Follow the instructions provided on that page. After installing it (i.e. uncompressing the tar 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
. To update the PATH env variable, you can update your .bashrc file (for further information on .bashrc and .bash_profile see http://www.joshstaiger.org/archives/2005/07/bash_profile_vs.html).
-
Clone, build and install the libdispatch library. The complete instructions for building and installing this library are here, though, all you need to do is just this
git clone https://github.com/apple/swift-corelibs-libdispatch.git && cd swift-corelibs-libdispatch && git submodule init && git submodule update && sh ./autogen.sh && ./configure --with-swift-toolchain=<path-to-swift>/usr --prefix=<path-to-swift>/usr && make && make install
-
Clone this repository,
develop
branch
git clone -b develop https://github.com/IBM-Swift/Kitura
- build and run Kitura Sample
make run
You should see a message that says "Listening on port 8090". The result executable is located in .build/debug
folder in the cloned repository: ./.build/debug/KituraSample
make test
Let's write our first Kitura-based Web Application written in Swift!
- First we create a new project directory
mkdir myFirstProject
- Next we initialize this project as a new Swift package project
cd myFirstProject
swift build --init
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
- Now we add Kitura as a dependency for your project (Package.swift):
import PackageDescription
let package = Package(
name: "myFirstProject",
dependencies: [
.Package(url: "https://github.com/IBM-Swift/Kitura-router.git", versions: Version(0,3,0)..<Version(0,4,0)),
])
- Import the modules in your code (Sources/main.swift):
import KituraRouter
import KituraNet
import KituraSys
- Add a router and a path:
let router = Router()
router.get("/") {
request, response, next in
response.status(HttpStatusCode.OK).send("Hello, World!")
next()
}
- Create and start a HTTPServer:
let server = HttpServer.listen(8090, delegate: router)
Server.run()
- Sources/main.swift file should now look like this:
import KituraRouter
import KituraNet
import KituraSys
let router = Router()
router.get("/") {
request, response, next in
response.status(HttpStatusCode.OK).send("Hello, World!")
next()
}
let server = HttpServer.listen(8090, delegate: router)
Server.run()
- Compile your application:
- Mac OS X:
swift build -Xcc -fblocks -Xswiftc -I/usr/local/include -Xlinker -L/usr/local/lib
- Linux:
swift build -Xcc -fblocks
Or copy 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
Feel free to visit our Wiki (which, btw, is in very early stages).
This library is licensed under Apache 2.0. Full license text is available in LICENSE.