Getting Started Guide

Install RHEL 7 using one of the following images:

Use the following command to register the system.

$ sudo subscription-manager register

You can also register the system by following the appropriate steps in Registering and Unregistering a System in the Red Hat Subscription Management document.

Display a list of all subscriptions that are available for your system and identify the pool ID for the subscription.

$ sudo subscription-manager list --available

This command displays the subscription name, unique identifier, expiration date, and other details related to it. The pool ID is listed on a line beginning with Pool ID.

Attach the subscription that provides access to the dotNET on RHEL repository. Use the pool ID you identified in the previous step.

$ sudo subscription-manager attach --pool=<appropriate pool ID from the subscription>

Enable the .NET Core channel for Red Hat Enterprise 7 Server, Red Hat Enterprise 7 Workstation, or HPC Compute Node with one of the following commands, respectively.

$ sudo subscription-manager repos --enable=rhel-7-server-dotnet-rpms
$ sudo subscription-manager repos --enable=rhel-7-workstation-dotnet-rpms
$ sudo subscription-manager repos --enable=rhel-7-hpc-node-dotnet-rpms

Verify the list of subscriptions attached to your system.

$ sudo subscription-manager list --consumed

Install the scl tool.

$ sudo yum install scl-utils

Install .NET Core 2.1 and all of its dependencies.

$ sudo yum install rh-dotnet21 -y

Enable the rh-dotnet21 Software Collection environment so you can run dotnet commands in the bash shell

This procedure installs the .NET Core 2.1 runtime with the latest 2.1 SDK. When a newer SDK becomes available, it automatically installs as a package update.

$ scl enable rh-dotnet21 bash

This command does not persist; it creates a new shell, and the dotnet command is only available within that shell. If you log out, use another shell, or open up a new terminal, the dotnet command is no longer enabled.

Run the following command to verify the installation succeeded.

$ dotnet --info
.NET Core SDK (reflecting any global.json):
 Version:   2.1.300
 Commit:    ded465c666

Runtime Environment:
 OS Name:     rhel
 OS Version:  7
 OS Platform: Linux
 RID:         rhel.7-x64
 Base Path:   /opt/rh/rh-dotnet21/root/usr/lib64/dotnet/sdk/2.1.300/

Host (useful for support):
  Version: 2.1.0
  Commit:  N/A

  .NET Core SDKs installed:
  2.1.300 [/opt/rh/rh-dotnet21/root/usr/lib64/dotnet/sdk]

.... omitted

Create a new Console application in a directory called hello-world.

$ dotnet new console -o hello-world
  The template "Console Application" was created successfully.

  Processing post-creation actions...
  Running 'dotnet restore' on hello-world/hello-world.csproj...
  Restoring packages for /home/<USER>/hello-world/hello-world.csproj...
  Generating MSBuild file /home/<USER>/hello-world/obj/hello-world.csproj.nuget.g.props.
  Generating MSBuild file /home/<USER>/hello-world/obj/hello-world.csproj.nuget.g.targets.
  Restore completed in 224.85 ms for /home/<USER>/hello-world/hello-world.csproj.

  Restore succeeded.

Run the project.

$ cd hello-world
$ dotnet run
Hello World!

Create a new mvc project in a directory named mvc_runtime_example.

$ dotnet new mvc -o mvc_runtime_example --no-restore
$ cd mvc_runtime_example

Restore and publish the project.

$ dotnet restore -r rhel.7-x64
$ dotnet publish -f netcoreapp2.1 -c Release -r rhel.7-x64 --self-contained false /p:MicrosoftNETPlatformLibrary=Microsoft.NETCore.App

Create the Dockerfile.

$ cat > Dockerfile <<EOF
FROM registry.redhat.io/dotnet/dotnet-21-runtime-rhel7

ADD bin/Release/netcoreapp2.1/rhel.7-x64/publish/ .

CMD ["dotnet", "mvc_runtime_example.dll"]
EOF

Build your image.

$ podman build -t dotnet-21-runtime-example .

Run your image.

$ podman run -d -p8080:8080 dotnet-21-runtime-example

If you are a system administrator or otherwise have sufficient permissions, change to the openshift project. Using the openshift project allows you to globally update the image stream definitions.

$ oc project openshift

If you do not have permissions to use the openshift project, you can still update your project definitions starting with Step 2.

Run the following commands to list all available .NET Core image versions.

$ oc describe is dotnet -n openshift
$ oc describe is dotnet

The output shows installed images or the message Error from server (NotFound) if no images are installed.

To pull the images, OpenShift needs credentials for authenticating with the registry.redhat.io server. These credentials are stored in a secret.

Enter the following command to list secrets. The first column shows the secret name.

$ oc get secret | grep kubernetes.io/dockerc

To check the contents of a secret, you can decode the .dockercfg or .dockerconfigjson data from Base64 format. This allows you to see if you already have credentials for the registry.redhat.io server. Enter the following command to show the .dockercfg section in a secret.

$ oc get secret <secret-name> -o yaml | grep .dockercfg
  .dockercfg: eyJyZWdpc3RyeS5yZWRoYXQuaW8iOnsidXNlcm5hbWUiOiIqKioqKioqKiIsInBhc3N3b3JkIjoiKioqKioqKioiLCJlbWFpbCI6InVudXNlZCIsImF1dGgiOiJLaW9xS2lvcUtpbzZLaW9xS2lvcUtpbz0ifX0=

Copy and paste the output in the following command to convert it from Base64 format. The example below shows the credentials for the registry.redhat.io server.

$ echo eyJyZWdpc3RyeS5yZWRoYXQuaW8iOnsidXNlcm5hbWUiOiIqKioqKioqKiIsInBhc3N3b3JkIjoiKioqKioqKioiLCJlbWFpbCI6InVudXNlZCIsImF1dGgiOiJLaW9xS2lvcUtpbzZLaW9xS2lvcUtpbz0ifX0= | base64 -d
{"registry.redhat.io":{"username":"********","password":"********","email":"unused","auth":"KioqKioqKio6KioqKioqKio="}}

You need to add a secret if there is no secret listed with credentials for the registry.redhat.io server.

Red Hat account credentials are used for registry.redhat.io access. If you are a customer with entitlements to Red Hat products, you already have account credentials to use. These are typically the same credentials used to log in to the Red Hat Customer Portal. To verify your Red Hat credentials, enter the following command and attempt to log in.

$ podman login registry.redhat.io

If you cannot log in, you first need to get an account with Red Hat. See Red Hat Container Registry Authentication for additional information. If you can log in, enter the following commands to create the secret.

$ oc create secret docker-registry redhat-registry \
    --docker-server=registry.redhat.io \
    --docker-username=<user-name> \
    --docker-password=<password> \
    --docker-email=unused
$ oc secrets link default redhat-registry --for=pull
$ oc secrets link builder redhat-registry

After creating the secret, enter the following command to import new image streams.

$ oc create -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.json

If image streams were already installed, use the replace command to update the image stream definitions.

$ oc replace -f https://raw.githubusercontent.com/redhat-developer/s2i-dotnetcore/master/dotnet_imagestreams.json

Run the following commands to deploy the ASP.NET Core application, which is in the app folder on the dotnetcore-2.1 branch of the redhat-developer/s2i-dotnetcore-ex GitHub repository.

$ oc new-app --name=exampleapp 'dotnet:2.1~https://github.com/redhat-developer/s2i-dotnetcore-ex#dotnetcore-2.1' --build-env DOTNET_STARTUP_PROJECT=app

Use the oc logs command to track progress of the build.

$ oc logs -f bc/exampleapp

View the deployed application once the build is finished.

$ oc logs -f dc/exampleapp

At this point, the application is accessible within the project. To make it accessible externally, use the oc expose command. You can then use oc get routes to find the URL.

$ oc expose svc/exampleapp
$ oc get routes

Publish your application as described in Publish Applications. For example, the following commands create a new web application and publish it.

$ dotnet new web -o webapp
$ cd webapp
$ dotnet publish -c Release /p:MicrosoftNETPlatformLibrary=Microsoft.NETCore.App

Create a new binary build using the oc new-build command.

$ oc new-build --name=mywebapp dotnet:2.1 --binary=true

Start a build using the oc start-build command, specifying the path to the binary artifacts on your local machine.

$ oc start-build mywebapp --from-dir=bin/Release/netcoreapp2.1/publish

Create a new application using the oc new-app command.

$ oc new-app mywebapp

Change to the project where Jenkins is (or will be) deployed.

$ oc project <projectname>

Create a dotnet-jenkins-slave.yaml file. The value used for the <serviceAccount> element is the account used by the Jenkins slave. If no value is specified, the default service account is used.

kind: ConfigMap
apiVersion: v1
metadata:
  name: dotnet-jenkins-slave-21
  labels:
    role: jenkins-slave
data:
  dotnet21: |-
    <org.csanchez.jenkins.plugins.kubernetes.PodTemplate>
      <inheritFrom></inheritFrom>
      <name>dotnet-21</name>
      <instanceCap>2147483647</instanceCap>
      <idleMinutes>0</idleMinutes>
      <label>dotnet-21</label>
      <serviceAccount>jenkins</serviceAccount>
      <nodeSelector></nodeSelector>
      <volumes/>
      <containers>
        <org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
          <name>jnlp</name>
          <image>registry.access.redhat.com/dotnet/dotnet-21-jenkins-slave-rhel7:latest</image>
          <privileged>false</privileged>
          <alwaysPullImage>true</alwaysPullImage>
          <workingDir>/tmp</workingDir>
          <command></command>
          <args>${computer.jnlpmac} ${computer.name}</args>
          <ttyEnabled>false</ttyEnabled>
          <resourceRequestCpu></resourceRequestCpu>
          <resourceRequestMemory></resourceRequestMemory>
          <resourceLimitCpu></resourceLimitCpu>
          <resourceLimitMemory></resourceLimitMemory>
          <envVars/>
        </org.csanchez.jenkins.plugins.kubernetes.ContainerTemplate>
      </containers>
      <envVars/>
      <annotations/>
      <imagePullSecrets/>
      <nodeProperties/>
    </org.csanchez.jenkins.plugins.kubernetes.PodTemplate>

Import the configuration into the project.

$ oc create -f dotnet-jenkins-slave.yaml

The slave image can now be used.

Create the buildconfig.yaml file.

kind: BuildConfig
apiVersion: v1
metadata:
  name: dotnetapp-build
spec:
  strategy:
    type: JenkinsPipeline
    jenkinsPipelineStrategy:
      jenkinsfile: |-
        node("dotnet-21") {
          stage('clone sources') {
            sh "git clone https://github.com/redhat-developer/s2i-dotnetcore-ex --branch dotnetcore-2.1 ."
          }
          stage('publish') {
            dir('app') {
              sh "dotnet publish -c Release /p:MicrosoftNETPlatformLibrary=Microsoft.NETCore.App"
            }
          }
          stage('create image') {
            dir('app') {
              sh 'oc new-build --name=dotnetapp dotnet:2.1 --binary=true || true'
              sh 'oc start-build dotnetapp --from-dir=bin/Release/netcoreapp2.1/publish --follow'
            }
          }
        }

Import the BuildConfig file to OpenShift.

$ oc create -f buildconfig.yaml

Click Start Pipeline. It may take a while for the build to start because the Jenkins image(s) need to be downloaded first.

During the build you can watch the different pipeline stages complete in the OpenShift console. You can also click View Log to see the pipeline stages complete in Jenkins.