Sample application for the Kitura Web Framework
This Kitura sample shows off the powerful features available in Kitura 2, baking several demos into one project. You can access the individual examples by navigating to their specific page in a browser.
It features the following:
- Raw and Codable routing examples
- Database persistence using Swift-Kuery-ORM
- Sessions persistence using Kitura-Session
- Rendering templates with Markdown and Stencil
- HTTP Basic and Oauth2 authentication with Kitura-Credentials
- A Kitura WebSocket based chat server
Getting Set Up
git clone https://github.com/IBM-Swift/Kitura-Sample.git
You should see a message Listening on port 8080. You may need to click "Allow" if a security pop up appears, dependent on your firewall settings.
- Open your browser at http://localhost:8080.
Hello World: Kitura Raw routing
This page demonstrates routing in Kitura using the Raw HTTP request and response.
When you make a get request to localhost:8080/hello the server will send back with the traditional Hello World response.
You can then send HTTP POST or DELETE requests to change the name that the server will respond with.
Kitura Codable routing
This page demonstrates Codable routing in Kitura where you work directly with Codable models.
You make HTTP requests to localhost:8080/books to GET, POST or DELETE a swift model of a book.
You can then search all your books using query parameters.
Database persistence using Swift-Kuery-ORM
This page demonstrates a server which will save and retrieve a students
Grades using the Swift-Kuery-ORM API.
The example initially uses a dummy database but you can connect it to a live PostgreSQL database by by following the steps below:
- In terminal, set up a PostgreSQL database:
brew install postgresql brew services start postgresql createdb school
SwiftKueryPostgreSQLto your dependancies in
- Switch the connection to
This adds persistance to the data, meaning even if the server is restarted the grades will be stored.
Sessions persistence using Kitura-Session
This page demonstrates a server which will save an array of
Books in a session. This array is unique to a single user who is authenticated via http cookies. You can test the session by saving books a private and a normal browser window and observing that both windows maintain their own array. The page includes example for both Raw and Codable Session routes.
Stencil Templating Engine
The route looks for a Stencil template file in a subdirectory called
Views and renders an HTML page using it. This allows for you to create dynamic web pages by inserting data from your server into your HTML.
Rendering Markdown files
The route looks for a Markdown file in a subdirectory called
Views and generates an HTML page using it. This allows for you to server Markdown formatted files as web pages.
This demo sets up a local chat server using Kitura's WebSocket library, and the UI mimicks a chat room. Two separate browser windows pointed to the
/chat route can be used to represent two people in the chat room if the project is running on localhost.
HTTP Basic Authentication
This page demonstrates how to protect Raw and Codable routes using HTTP Basic Authentication. You can sign up to the server by providing a username and password and then to access your desired route you must provide that username and password or your request will be rejected as unauthorized.
OAuth2 token authentication
This page demonstrates how to protect Raw and Codable routes using OAuth2 tokens. You generate a user access token for either facebook or google (Which would normally be performed by another application) and send an HTTP request to the server with that token. The server authenticates the token with the provider to identify the user and allow access to the protected route. If the token is incorrect the request is rejected as unauthorized.
OAuth2 token authentication
This page demonstrates how to authenticate a user with OAuth2 by redirecting to a trusted third party. You create an OAuth2 authentication application with either AppID, Facebook or Google and add its credentials to Kitura Sample. You can then log in with any of the providers to access the protected route. If the user is not logged in the request is rejected as unauthorized.
- Start the Kitura-Sample server
- Go to http://localhost:8080/openapi to view OpenAPI definition
- Go to http://localhost:8080/openapi/ui to view OpenAPI User Interface
To run the tests locally, run
swift test from the Kitura-Sample directory.
Running in Xcode
You can also run this sample application inside Xcode. For more details, visit kitura.io.
Running with Docker
A description of the files related to Docker can be found in the Docker files setion. To build the two docker images, run the following commands from the root directory of the project:
docker build -t myapp-run .
docker build -t myapp-build -f Dockerfile-tools .You may customize the names of these images by specifying a different value after the
To compile the application using the tools docker image, run:
docker run -v $PWD:/swift-project -w /swift-project myapp-build /swift-utils/tools-utils.sh build release
To run the application:
docker run -it -p 8080:8080 -v $PWD:/swift-project -w /swift-project myapp-run sh -c .build-ubuntu/release/Kitura-Sample
Deploy to Cloud Foundry
- Log in to IBM Cloud
bluemix api https://api.ng.bluemix.net bluemix login bluemix target -o <YOUR_ORG> -s <YOUR_DEV_SPACE>
where YOUR_ORG is the organisation you used when signing up to IBM Cloud and YOUR_DEV_SPACE is the space you created.
- Deploy your application to IBM Cloud
bx app push
This sample app is licensed under the Apache License, Version 2.0.
Help us keep the lights on
2.7.0 - May 1, 2019
- Updated for Swift 5, Kitura 2.7 and Kitura-NIO 2.0
- ORM and database connectivity examples
- Authentication and Sessions examples
2.3.0 - Apr 23, 2018
- Update dependencies for Kitura 2.3 (#85)