Home

Awesome

Kitura

Build Status - Master Join the chat at https://gitter.im/IBM-Swift/Kitura macOS Linux Apache 2

IBM Cloud starter application for Kitura web framework and HTTP server

What is Kitura?

Kitura is a new, modular, package-based web framework written in the Swift language, that allows you to build web services with complex routes, easily.

Kitura-Starter Overview

Kitura-Starter is a Kitura based server application that you can use as a starting point to get your own Kitura application up and running on the IBM Cloud. Also, if you'd like to run this app locally, you can do so on your macOS or Ubuntu 18.04 system.

Application Requirements

To compile and run this starter application on your local system, you need to install the Swift compiler for your platform. This version of Kitura-Starter works with the Swift 5.0+ release binaries. Compatibility with other Swift versions is not guaranteed.

For further details on executing Kitura-based applications locally, please see Kitura's instructions for installation on macOS and on Linux since system level dependencies may be required before attempting to execute this starter app.

If you are interested in manually deploying the application to the IBM Cloud, you'll need to install the IBM Cloud command line on your system. Once it is installed, you can use it to authenticate and access your IBM Cloud organization(s) and spaces. You can find further details on how to deploy this sample application to the IBM Cloud in a subsequent section.

Clone, build, and run locally

Once you have installed the Swift compiler and any system level dependencies required by the Kitura framework, you can proceed with the steps described in this section.

  1. Clone this repo using git clone https://github.com/IBM-Cloud/Kitura-Starter.git.

  2. Go to the root folder of this repo on your system and issue the swift build command to compile the application:

$ swift build
Fetching https://github.com/IBM-Swift/FileKit.git
Fetching https://github.com/IBM-Swift/Kitura-net.git
Fetching https://github.com/IBM-Swift/Kitura-TemplateEngine.git
Fetching https://github.com/IBM-Swift/BlueSocket.git
Fetching https://github.com/apple/swift-log.git
Fetching https://github.com/IBM-Swift/TypeDecoder.git
Fetching https://github.com/IBM-Swift/BlueSignals.git
Fetching https://github.com/IBM-Swift/Swift-cfenv.git
Fetching https://github.com/IBM-Swift/Health.git
Fetching https://github.com/IBM-Swift/OpenSSL.git
Fetching https://github.com/IBM-Swift/KituraContracts.git
Fetching https://github.com/IBM-Swift/BlueSSLService.git
Fetching https://github.com/IBM-Swift/Kitura.git
Fetching https://github.com/IBM-Swift/LoggerAPI.git
Fetching https://github.com/IBM-Swift/CloudEnvironment.git
Fetching https://github.com/IBM-Swift/Configuration.git
Fetching https://github.com/IBM-Swift/HeliumLogger.git
Completed resolution in 41.89s
Cloning https://github.com/IBM-Swift/LoggerAPI.git
Resolving https://github.com/IBM-Swift/LoggerAPI.git at 1.9.0
Cloning https://github.com/IBM-Swift/Kitura-TemplateEngine.git
Resolving https://github.com/IBM-Swift/Kitura-TemplateEngine.git at 2.0.1
Cloning https://github.com/IBM-Swift/KituraContracts.git
Resolving https://github.com/IBM-Swift/KituraContracts.git at 1.1.3
Cloning https://github.com/IBM-Swift/Health.git
Resolving https://github.com/IBM-Swift/Health.git at 1.0.5
Cloning https://github.com/IBM-Swift/TypeDecoder.git
Resolving https://github.com/IBM-Swift/TypeDecoder.git at 1.3.3
Cloning https://github.com/IBM-Swift/Swift-cfenv.git
Resolving https://github.com/IBM-Swift/Swift-cfenv.git at 6.0.3
Cloning https://github.com/IBM-Swift/BlueSSLService.git
Resolving https://github.com/IBM-Swift/BlueSSLService.git at 1.0.48
Cloning https://github.com/IBM-Swift/BlueSocket.git
Resolving https://github.com/IBM-Swift/BlueSocket.git at 1.0.48
Cloning https://github.com/IBM-Swift/Configuration.git
Resolving https://github.com/IBM-Swift/Configuration.git at 3.0.4
Cloning https://github.com/IBM-Swift/FileKit.git
Resolving https://github.com/IBM-Swift/FileKit.git at 0.0.2
Cloning https://github.com/IBM-Swift/Kitura-net.git
Resolving https://github.com/IBM-Swift/Kitura-net.git at 2.3.0
Cloning https://github.com/IBM-Swift/Kitura.git
Resolving https://github.com/IBM-Swift/Kitura.git at 2.8.0
Cloning https://github.com/IBM-Swift/CloudEnvironment.git
Resolving https://github.com/IBM-Swift/CloudEnvironment.git at 9.1.0
Cloning https://github.com/IBM-Swift/HeliumLogger.git
Resolving https://github.com/IBM-Swift/HeliumLogger.git at 1.9.0
Cloning https://github.com/apple/swift-log.git
Resolving https://github.com/apple/swift-log.git at 1.1.0
[169/169] Linking Kitura-Starter

Once the application is compiled, you can start the server (note that the executable file is located in the .build/debug directory: ./.build/debug/Kitura-Starter):

$ ./.build/debug/Kitura-Starter
 INFO: Kitura_Starter main.swift line 29 - Server will be started on 'http://localhost:8080'.
 INFO: listen(on:) HTTPServer.swift line 73 - Listening on port 8080

Once the server starts, you should see the message Listening on port 8080 as shown above.

  1. Open your browser at http://localhost:8080 to access the welcome page for the Kitura-Starter app. This page displays static HTML content served from the Kitura-based server application. You can explore the public folder in the repo to see the HTML file and related resources (e.g. images, CSS file)

  2. To access a plain text greeting, point your browser to http://localhost:8080/hello.

  3. To perform a POST operation, use your preferred REST client (e.g. Postman) to send a string to http://localhost:8080/hello. You should get a text response that includes the string you sent to the endpoint.

  4. To receive a JSON payload, point your browser to http://localhost:8080/json.

  5. To receive a JSON payload that states the health of the application, point your browser to http://localhost:8080/health.

Pushing the application to IBM Cloud

Using the Deploy to IBM Cloud button

Clicking on the button below deploys this starter application to the IBM Cloud. The manifest.yml file [included in the repo] is parsed to obtain the name of the application and configuration details. For further details on the structure of the manifest.yml file, see the Cloud Foundry documentation.

Deploy to IBM Cloud

Once deployment to the IBM Cloud is completed, you can access the route assigned to your application using the web browser of your choice. You should then see the welcome page for the Kitura-Starter app! To access a plain text greeting, point your browser to http://<application_route>/hello. To perform a POST operation, use your preferred REST client (e.g. Postman) to send a string to http://<application_route>/hello. You should get a text response that includes the string you sent to the endpoint. Finally, to receive a JSON payload, point your browser to http://<application_route>/json.

Note that the IBM Cloud buildpack for Swift is used for the deployment of this app to the IBM Cloud. This IBM Cloud buildpack for Swift is currently installed in the following IBM Cloud regions: US South, United Kingdom, and Sydney.

Using the IBM Cloud command line

You can also manually deploy the app to the IBM Cloud. Though not as magical as using the IBM Cloud button above, manually deploying the app gives you some insights about what is happening behind the scenes. Remember that you'd need the IBM Cloud command line installed on your system to deploy the app to the IBM Cloud.

Using the IBM Cloud command line you can get a list of the buildpacks (along with their versions) that are installed on the IBM Cloud. Note that you should be already logged on to the IBM Cloud before you issue any of the following commands.

Executing the ibmcloud cf buildpacks above command should result in output similar to the following:

$ ibmcloud cf buildpacks
Invoking 'cf buildpacks'...

Getting buildpacks...

buildpack                              position   enabled   locked   filename
liberty-for-java                        1          true      false    buildpack_liberty-for-java_v3.8-20170308-1507.zip
sdk-for-nodejs                          2          true      false    buildpack_sdk-for-nodejs_v3.11-20170303-1144.zip
swift_buildpack                         3          true      false    buildpack_swift_v2.0.19-20170328-1639.zip
dotnet-core                             4          true      false    buildpack_dotnet-core_v1.0.10-20170124-1145.zip
java_buildpack                          5          true      false    java-buildpack-v3.13.zip
ruby_buildpack                          6          true      false    ruby_buildpack-cached-v1.6.34.zip
nodejs_buildpack                        7          true      false    nodejs_buildpack-cached-v1.5.29.zip
go_buildpack                            8          true      false    go_buildpack-cached-v1.7.18.zip
python_buildpack                        9          true      false    python_buildpack-cached-v1.5.15.zip
php_buildpack                           10         true      false    php_buildpack-cached-v4.3.27.zip
xpages_buildpack                        11         true      false    xpages_buildpack_v1.2.5-20170320-2106.zip
staticfile_buildpack                    15         true      false    staticfile_buildpack-cached-v1.3.17.zip
binary_buildpack                        16         true      false    binary_buildpack-cached-v1.0.9.zip
swift_v2_0_2-20161118-1326              21         true      false    buildpack_swift_v2.0.2-20161118-1326.zip
dotnet-core_v1_0_6-20161205-0912        22         true      false    buildpack_dotnet-core_v1.0.6-20161205-0912.zip
sdk-for-nodejs_v3_11-20170206-1113      23         true      false    buildpack_sdk-for-nodejs_v3.11-20170206-1113.zip
liberty-for-java_v3_7-20170118-2046     24         true      false    buildpack_liberty-for-java_v3.7-20170118-2046.zip
xpages_buildpack_v1_2_3-20170315-1027   25         true      false    xpages_buildpack_v1.2.3-20170315-1027.zip
dotnet_core_buildpack                   26         true      false    dotnet-core_buildpack-cached-v1.0.11.zip
swift_buildpack_v2_0_4-20170125-2344    27         true      false    buildpack_swift_v2.0.4-20170125-2344.zip

Looking at the output above, we can see that the Swift buildpack is installed on the IBM Cloud. This will allow a seamless deployment of the starter application to the IBM Cloud.

After you have cloned this Git repo, go to its root folder on your system and issue the ibmcloud app push command. Here is some sample output from the Swift buildpack (v2.0.19) running Swift 5.0:

$ ibmcloud app push
Using manifest file /Users/olivieri/git/Kitura-Starter/manifest.yml

Creating app Kitura-Starter in org roliv@us.ibm.com / space dev as roliv@us.ibm.com...
OK

Creating route kitura-starter-unsanctified-intervalometer.mybluemix.net...
OK

Binding kitura-starter-unsanctified-intervalometer.mybluemix.net to Kitura-Starter...
OK

Uploading Kitura-Starter...
Uploading app files from: /Users/olivieri/git/Kitura-Starter
Uploading 28K, 17 files
Done uploading               
OK

Starting app Kitura-Starter in org roliv@us.ibm.com / space dev as roliv@us.ibm.com...
Downloading swift_buildpack...
Downloaded swift_buildpack
Creating container
Downloading app package...
Downloaded app package (27.7K)
Staging...
-----> Buildpack version 2.0.19
-----> Default supported Swift version is 5.0
-----> Copying deb files to installation folder...
-----> No Aptfile found.
-----> Configure for apt-get installs...
-----> Writing profile script...
-----> Getting swift-5.0
       Cached swift-5.0
-----> Unpacking swift-5.0.tar.gz
-----> Getting clang-4.0.0
       Cached clang-4.0.0
-----> Unpacking clang-4.0.0.tar.xz
-----> .ssh directory and config file not found.
-----> Fetching Swift packages and parsing Package.swift files...
-----> Skipping cache restore (new swift signature)
       Fetching https://github.com/IBM-Swift/HeliumLogger.git
       Fetching https://github.com/IBM-Swift/Configuration.git
       Fetching https://github.com/IBM-Swift/CloudConfiguration.git
       Fetching https://github.com/IBM-Swift/BlueSocket.git
       Cloning https://github.com/IBM-Swift/Configuration.git
       Resolving https://github.com/IBM-Swift/Configuration.git at 0.2.4
       Cloning https://github.com/IBM-Swift/Kitura.git
       Resolving https://github.com/IBM-Swift/BlueSSLService.git at 0.12.30
       Resolving https://github.com/IBM-Swift/LoggerAPI.git at 1.6.0
       Fetching https://github.com/IBM-Swift/CCurl.git
       Fetching https://github.com/IBM-Swift/Kitura-TemplateEngine.git
       Cloning https://github.com/IBM-Swift/CEpoll.git
       Resolving https://github.com/IBM-Swift/CEpoll.git at 0.1.0
       Resolving https://github.com/IBM-Swift/HeliumLogger.git at 1.6.1
       Cloning https://github.com/IBM-Swift/Kitura-net.git
       Resolving https://github.com/IBM-Swift/BlueSocket.git at 0.12.41
       Fetching https://github.com/IBM-Swift/Kitura.git
       Fetching https://github.com/IBM-Swift/CEpoll.git
       Fetching https://github.com/IBM-Swift/Kitura-net.git
       Fetching https://github.com/IBM-Swift/BlueSSLService.git
       Fetching https://github.com/IBM-Swift/Swift-cfenv.git
       Fetching https://github.com/IBM-Swift/OpenSSL.git
       Fetching https://github.com/IBM-Swift/LoggerAPI.git
       Fetching https://github.com/IBM-Swift/SwiftyJSON.git
       Cloning https://github.com/IBM-Swift/Swift-cfenv.git
       Resolving https://github.com/IBM-Swift/Swift-cfenv.git at 4.0.0
       Cloning https://github.com/IBM-Swift/CCurl.git
       Resolving https://github.com/IBM-Swift/CCurl.git at 0.2.3
       Resolving https://github.com/IBM-Swift/Kitura.git at 1.6.3
       Cloning https://github.com/IBM-Swift/OpenSSL.git
       Resolving https://github.com/IBM-Swift/OpenSSL.git at 0.3.1
       Cloning https://github.com/IBM-Swift/HeliumLogger.git
       Cloning https://github.com/IBM-Swift/BlueSSLService.git
       Resolving https://github.com/IBM-Swift/Kitura-net.git at 1.6.2
       Cloning https://github.com/IBM-Swift/CloudConfiguration.git
       Resolving https://github.com/IBM-Swift/CloudConfiguration.git at 2.0.0
       Cloning https://github.com/IBM-Swift/BlueSocket.git
       Cloning https://github.com/IBM-Swift/SwiftyJSON.git
       Resolving https://github.com/IBM-Swift/SwiftyJSON.git at 15.0.6
       Cloning https://github.com/IBM-Swift/LoggerAPI.git
       Cloning https://github.com/IBM-Swift/Kitura-TemplateEngine.git
       Resolving https://github.com/IBM-Swift/Kitura-TemplateEngine.git at 1.6.0
-----> Additional packages to download: libcurl4-openssl-dev openssl libssl-dev
-----> libcurl4-openssl-dev is already installed.
-----> No additional packages to download.
-----> openssl is already installed.
-----> Installing system level dependencies...
-----> Building Package...
-----> libssl-dev is already installed.
-----> Skipping installation of App Management (debug)
-----> Build config: release
       Compile Swift Module 'LoggerAPI' (1 sources)
       Compile Swift Module 'KituraTemplateEngine' (1 sources)
       Compile Swift Module 'Socket' (3 sources)
       Compile Swift Module 'SwiftyJSON' (2 sources)
       Compile Swift Module 'Configuration' (6 sources)
       Compile Swift Module 'HeliumLogger' (2 sources)
       Compile Swift Module 'TestProgram' (1 sources)
       Compile Swift Module 'CloudFoundryEnv' (6 sources)
       Linking ./.build/release/TestProgram
       Compile Swift Module 'SSLService' (1 sources)
       Compile Swift Module 'AmazonConfig' (1 sources)
       Compile Swift Module 'CloudFoundryConfig' (2 sources)
       Compile Swift Module 'HerokuConfig' (1 sources)
       Compile CHTTPParser utils.c
       Compile CHTTPParser http_parser.c
       Linking CHTTPParser
       Compile Swift Module 'KituraNet' (34 sources)
       Compile Swift Module 'Kitura' (43 sources)
       Compile Swift Module 'Kitura_Starter' (2 sources)
       Linking ./.build/release/Kitura-Starter
-----> Copying dynamic libraries
-----> Copying binaries to 'bin'
-----> Cleaning up build files
-----> Saving cache (default):
-----> - Packages (nothing to cache)
-----> Optimizing contents of cache folder...
-----> Clearing previous swift cache
No start command specified by buildpack or via Procfile.
App will not start unless a command is provided at runtime.
Uploading droplet...
Exit status 0
Staging complete
Uploading droplet, build artifacts cache...
Uploading build artifacts cache...
Uploaded build artifacts cache (929B)
Uploading complete
Uploaded droplet (71.3M)
Destroying container
Successfully destroyed container

1 of 1 instances running

App started


OK

App Kitura-Starter was started using this command `Kitura-Starter`

Showing health and status for Kitura-Starter in org roliv@us.ibm.com / space dev as roliv@us.ibm.com...
OK

requested state: started
instances: 1/1
usage: 256M x 1 instances
urls: kitura-starter-unsanctified-intervalometer.mybluemix.net
last uploaded: Tue Mar 7 14:53:59 UTC 2017
stack: cflinuxfs2
buildpack: swift_buildpack

     state     since                    cpu    memory      disk      details
#0   running   2019-03-07 08:58:10 AM   0.0%   0 of 256M   0 of 1G

Once the application is pushed to and running on the IBM Cloud, you can access your application route to see the welcome page for the Kitura-Starter app. You can log on to your IBM Cloud account to find the route of your application or you can inspect the output from the execution of the ibmcloud app push command. The string value (e.g. Kitura-Starter-unfiducial-flab.eu-gb.mybluemix.net) shown next to the urls should contain the route. Use that route as the URL to access the sample server using the browser of your choice.

Kitura.io

Feel free to visit Kitura.io for our roadmap and tutorials.

Running the application in an IBM Container on the IBM Cloud

This starter application can also be run in an IBM Container on the IBM Cloud. The ibmcom/kitura-ubuntu Docker image extends the swift-ubuntu-docker image. Hence, the ibmcom/kitura-ubuntu image also uses Ubuntu v14.04 LTS. For details on how to create an IBM Container to execute a Swift application, please see 10 Steps To Running a Swift App in an IBM Container and Running Kitura in an IBM Container.

License

The Kitura-Starter sample app is licensed under Apache 2.0. Full license text is available in LICENSE.