IBM Cloud starter application for Kitura web framework and HTTP server
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 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.
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.
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.
-
Clone this repo using
git clone https://github.com/IBM-Cloud/Kitura-Starter.git. -
Go to the root folder of this repo on your system and issue the
swift buildcommand 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.
-
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
publicfolder in the repo to see the HTML file and related resources (e.g. images, CSS file) -
To access a plain text greeting, point your browser to http://localhost:8080/hello.
-
To perform a
POSToperation, 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. -
To receive a JSON payload, point your browser to http://localhost:8080/json.
-
To receive a JSON payload that states the health of the application, point your browser to http://localhost:8080/health.
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.
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.
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.
Feel free to visit Kitura.io for our roadmap and tutorials.
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.
The Kitura-Starter sample app is licensed under Apache 2.0. Full license text is available in LICENSE.