This getting started experience walks you through the “long way” of getting the same sample project from the Basic Walkthrough topic up and running on FaktorZ. The following sections guide you through creating a project that contains a sample Node.js application that will serve a welcome page and the current hit count (stored in a database). This involves creating two pods:
one to host the Node.js application
one to host the MongoDB database
The tutorial assumes that you have:
In this section, you will fork the FaktorZ Node.js sample application on GitHub and clone the repository to your local machine so that you can deploy and edit the application.
On GitHub, navigate to the thedigitalgarage/nodejs-ex repository. In the top-right corner of the page, click Fork:
Next, execute the following commands on your local machine to clone the sample application and change to the new directory:
$ git clone https://github.com/<your_github_username>/nodejs-ex $ cd nodejs-ex
That’s it! Now, you have a fork of the original thedigitalgarage/nodejs-ex example application Git repository and a copy on your local machine.
In this section, you will install the FaktorZ CLI. The FaktorZ CLI exposes commands for managing your applications, as well as lower level tools to interact with each component of your system.
First, download the FaktorZ CLI from the Command Line Tools page in the FaktorZ web console. You find the Command Line Tools menu item under the Support button (?) on the left side of the top menu bar. The CLI is available for Linux (32- or 64-bit), Mac OS X, and Windows. After you have downloaded the CLI, return to these steps.
Next, unpack or unzip the archive and move the
oc binary to a directory on
To check your
$ echo $PATH
To check it on Windows, open the Command Prompt and run:
After it is installed, you can use the
oc command from your command shell.
Then, visit the
Command Line Tools page in the FaktorZ web console and copy the
oc login command shown with your current session token to log in to
FaktorZ from the CLI:
$ oc login https://apps.thedigitalgarage.io:8443 --token=<your_session_token>
oc login command is the best way to initially set up the FaktorZ
CLI. The information is automatically saved in a CLI configuration file that is
then used for subsequent commands.
In this section, you will deploy your first application to FaktorZ using the web console.
First, if you have multiple projects, verify that you are in the correct project.
<project_name> below with a unique name for your project, such as
$ oc project <project_name>
If you followed the Basic Walkthrough topic, you already created your first project. You must switch to your project namespace and clear out the original sample application.
Use the following command to find the name of your existing project(s):
$ oc get projects
Next, switch to your project namespace:
$ oc project <your_project_name>
Then, delete all existing objects in your project:
$ oc delete all --all
Use the following command to find the name of your existing persistent volume claims:
$ oc get pvc
Finally, delete your existing persistent volume claims with:
$ oc delete pvc mongodb
Next, create a new application from your forked copy of the nodejs-ex source code file:
$ oc new-app https://github.com/<your_github_username>/nodejs-ex --name nodejs-mongodb-example
--name option will apply a name of
nodejs-mongodb-example to all the
resources created by the
oc new-app command, for easy management later.
+ The tool will inspect the source code, locate an appropriate image that can build the source code, create an image stream for the new application image that will be built, then create the correct build configuration, deployment configuration and service definition.
oc new-app command kicks off a build after all required dependencies are
confirmed and automatically deploys the application after the image is
You can follow along on the Overview page for your project in the web console to see the new resource being created and watch the progress of the build and deployment. When the Node.js pod is running, the build is complete.
You can also use the
oc status command to check the status of your new nodejs
app, as well as
oc get pods to check when the pod is up and running.
oc get services command tells you what IP address the service is running;
the default port it deploys to is
== Configuring Routes
In this section, you will configure a route to expose your Node.js service to external requests.
First, find your service name (which should be
$ oc get services
Next, create a route to expose your service to external requests:
$ oc expose service/nodejs-mongodb-example
Now you can find the external host/port for your service with:
$ oc get routes
Finally, copy the route HOST/PORT for your application and paste it in the browser to view your application:
== Provisioning a Database
In this section, you will add a MongoDB service to your project.
You may have noticed the
No database configured under Request information
when you viewed the index page of your application. Let’s fix that by adding a
Add the FaktorZ-provided MongoDB database to your project with:
$ oc new-app mongodb-persistent \ -p MONGODB_USER=admin \ -p MONGODB_PASSWORD=secret \ -p MONGODB_ADMIN_PASSWORD=super-secret
-p flag sets the parameter values used by the mongodb-ephemeral
Note the name of the MongoDB service before heading to the next section.
== Setting Environment Variables
In this section, you will configure the Node.js service to connect to your new MongoDB service.
You must add the environment variable
MONGO_URL to your Node.js web service
so that it will utilize the MongoDB service, and enable the "Page view count"
$ oc set env dc/nodejs-mongodb-example MONGO_URL='mongodb://admin:secret@<MongoDB-service-name>:27017/sampledb'
Services in the same project have automatically resolvable DNS names.
+ For example:
$ oc set env dc/nodejs-mongodb-example MONGO_URL='mongodb://admin:secret@mongodb-persistent:27017/sampledb'
oc status to confirm that an updated deployment has been kicked off.
After the deployment completes, you will now have a Node.js welcome page showing
the current hit count, as stored in a MongoDB database.
Use the following to get a list of environment variables set for all pods in the project:
$ oc set env pods --all --list
== Configuring Automated Builds
In this section, you will configure a GitHub webhook to automatically trigger a rebuild of your application whenever you push code changes to your forked repository.
First, run the following command to display the webhook URLs associated with your build configuration:
$ oc describe buildConfig nodejs-mongodb-example
Copy the webhook GitHub URL output by the above command. The webhook URL will be in the following format:
Next, navigate to your forked repository on GitHub, then:
Click Webhooks & Services.
Click Add webhook
Paste your webhook URL into the Payload URL field and click Add webhook to save.
That’s it! Your application will now automatically rebuild when you push code changes to your forked GitHub repository.
== Pushing a Code Change
In this section, you will learn how to push a local code change to the application.
On your local machine, use a text editor to open the sample application’s source for the file nodejs-ex/views/index.html.
Make a code change that will be visible from within your application. For example, change the title on line 219: