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
-
git clone https://github.com/IBM-Swift/Kitura-Sample.git
-
cd Kitura-Sample
-
swift run
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.
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.
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.
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
- Add
SwiftKueryPostgreSQL
to your dependancies inPackage.swift
- Switch the connection to
PostgreSQLConnection
inDatabaseRoutes.swift
This adds persistance to the data, meaning even if the server is restarted the grades will be stored.
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.
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.
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.
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.
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.
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.
The sample is using Kitura-OpenAPI to automatically generate OpenAPI (aka Swagger) Specification for it's Codable routes.
- 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.
You can also run this sample application inside Xcode. For more details, visit kitura.io.
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-t
option.
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
- 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.