Developers: Web Console Walkthrough

Browser Requirements

Review the browser versions and operating systems that can be used to access the web console.

ifdef::openshift-enterprise,openshift-dedicated,openshift-origin,digital-garage,faktorz

Creating a Project

To create an application, you must first create a new project, then select an InstantApp template. From there, begins the build process and creates a new deployment.

  1. Visit the web console in your browser. The web console uses a self-signed certificate, so if prompted, continue past a browser warning.

  2. Log in using the username and password recommended to you by your administrator.

  3. To create a new project, click New Project.

  4. Type a unique name, display name, and description for the new project.

  5. Click Create.

    The web console’s welcome screen loads.

Creating an Application

The Select Image or Template page gives you the option to create from a publicly accessible git repository, or from a template:

  1. If creating a new project did not automatically redirect you to the Select Image or Template page, you might need to click Add to Project.

  2. Click Browse, then select ruby from the drop-down list.

  3. Click the ruby:latest builder image.

  4. Type a name for your application, and specify the Git Repository URL, which is https://github.com/<your_github_username>/ruby-ex.git.

  5. Optionally, click Show advanced routing, build, and deployment options, though by default this example application automatically creates a route, webhook trigger, and build change triggers.

  6. Click Create.

    After creation, some of these settings can be modified from the web console by clicking Browse, Builds, select your build, then click Actions, and either Edit or Edit YAML.

Creating your application might take some time. You can follow along on the Overview page of the web console to see the new resources being created, and watch the progress of the build and deployment.

While the Ruby pod is being created, its status is shown as pending. The Ruby pod then starts up and displays its newly-assigned IP address. When the Ruby pod is running, the build is complete.

Viewing the Running Application

To view your new application:

  1. In the web console, view the overview page to determine the web address for the application. For example, under SERVICE: RUBY-EX you should see something similar to: ruby-ex-my-test.example.openshiftapps.com.

  2. Visit the web address for your new application.

Configuring Automated Builds

You forked the source code for this application from the FaktorZ GitHub repository. Therefore, you can use a webhook to automatically trigger a rebuild of your application whenever you push code changes to your forked repository.

To set up a webhook for your application:

  1. From the Web Console, navigate to the project containing your application.

  2. Click the Browse tab, then click Builds.

  3. Click your build name, then click the Configuration tab.

  4. Click Copy next to GitHub webhook URL to copy your webhook payload URL.

  5. Navigate to your forked repository on GitHub, then click Settings.

  6. Click Webhooks & Services.

  7. Click Add webhook.

  8. Paste your webhook URL into the Payload URL field.

  9. Click Add webhook to save.

GitHub now attempts to send a ping payload to your FaktorZ server to ensure that communication is successful. If you see see a green check mark appear next to your webhook URL, then it is correctly configured. Hover your mouse over the check mark to see the status of the last delivery.

The next time you push a code change to your forked repository, your application will automatically rebuild.

Writing a Code Change

To work locally and then push changes to your application:

  1. On your local machine, use a text editor to change the sample application’s source for the file ruby-ex/config.ru

  2. Make a code change that will be visible from within your application. For example: on line 229, change the title from Welcome to your Ruby application on ` to `This is my Awesome Application, then save your changes.

  3. Commit the change in git, and push the change to your fork.

    If your webhook is correctly configured, your application will immediately rebuild itself based on your changes. Once the rebuild is successful, view your updated application using the route that was created earlier.

Now going forward, all you need to do is push code updates and FaktorZ handles the rest.

Manually Rebuilding Images

You may find it useful to manually rebuild an image if your webhook is not working, or if a build fails and you do not want to change the code before restarting the build. To manually rebuild the image based on your latest committed change to your forked repository:

  1. Click the Browse tab, then click Builds.

  2. Find your build, then click Start Build.

endif::openshift-enterprise,openshift-dedicated,openshift-origin,digital-garage,faktorz