Merge pull request #488 from hpehl/guides

Add guides to wildfly.org

_config.yml

@@ -64,24 +64,27 @@ asciidoctor:
 
 # Pages permalink
 defaults:
-  -
-    scope:
+  - scope:
+      path: ""
       type: "posts"
     values:
       permalink: /news/:year/:month/:day/:title/
-  -
-    scope:
+  - scope:
       path: "" # an empty string here means all files in the project
       type: "docs" # previously `post` in Jekyll 2.2.
     values:
       layout: "docs"
+  - scope:
+      path: "guides" # an empty string here means all files in the project
+    values:
+      layout: "guide"
 
 ############################################################
 # Site configuration for the Jekyll 3 Pagination Gem
 # The values here represent the defaults if nothing is set
 pagination:
-  
-  # Site-wide kill switch, disabled here it doesn't run at all 
+
+  # Site-wide kill switch, disabled here it doesn't run at all
   enabled: true
 
   # Set to 'true' to enable pagination debugging. This can be enabled in the site config or only for individual pagination pages
@@ -95,15 +98,15 @@ pagination:
 
   # The permalink structure for the paginated pages (this can be any level deep)
   permalink: '/page/:num/' # Pages are index.html inside this folder (default)
-  #permalink: '/page/:num.html' # Pages are simple html files 
+  #permalink: '/page/:num.html' # Pages are simple html files
   #permalink: '/page/:num' # Pages are html files, linked jekyll extensionless permalink style.
 
   # Optional the title format for the paginated pages (supports :title for original page title, :num for pagination page number, :max for total number of pages)
   title: ':title - page :num'
 
   # Limit how many pagenated pages to create (default: 0, means all)
   limit: 0
-  
+
   # Optional, defines the field that the posts should be sorted on (omit to default to 'date')
   sort_field: 'date'
 
@@ -116,13 +119,13 @@ pagination:
   # Optional, the default tag to use, omit to disable
   tag: ''
 
-  # Optional, the default locale to use, omit to disable (depends on a field 'locale' to be specified in the posts, 
+  # Optional, the default locale to use, omit to disable (depends on a field 'locale' to be specified in the posts,
   # in reality this can be any value, suggested are the Microsoft locale-codes (e.g. en_US, en_GB) or simply the ISO-639 language code )
-  locale: '' 
+  locale: ''
 
- # Optional,omit or set both before and after to zero to disable. 
- # Controls how the pagination trail for the paginated pages look like. 
-  trail: 
+ # Optional,omit or set both before and after to zero to disable.
+ # Controls how the pagination trail for the paginated pages look like.
+  trail:
     before: 2
     after: 2
 

_data/guides.yaml

@@ -0,0 +1,49 @@
+
+---
+categories:
+  - category: Get Started
+    cat-id: get-started
+    guides:
+      - title: Getting Started with WildFly
+        url: /get-started
+        description: Build and run a Jakarta EE application with WildFly in a few minutes
+  - category: Observability
+    cat-id: observability
+    guides:
+      - title: Configuring Logging for your Application
+        url: /guides/application-logging
+        description: Learn how to setup and configure logging in WildFly.
+  - category: Security
+    cat-id: security
+    guides:
+      - title: Securing WildFly Apps with OpenID Connect on OpenShift
+        url: /guides/security-oidc-openshift
+        description: Learn how to secure applications deployed to WildFly on OpenShift with OpenID Connect.
+      - title: Identity Propagation with OpenID Connect
+        url: /guides/security-oidc-identity-propagation
+        description: Learn how to propagate identities within a deployment and across deployments when securing apps with OpenID Connect.
+      - title: Securing WildFly Apps with Auth0 on OpenShift
+        url: /guides/security-oidc-auth0-openshift
+        description: Learn how to secure applications deployed to WildFly on OpenShift with the Auth0 OpenID provider.
+      - title: Securing the WildFly Management Console with OpenID Connect
+        url: /guides/security-oidc-management-console
+        description: Learn how to secure the WildFly management console with the Keycloak OpenID provider.
+      - title: Securing WildFly Apps with SAML on OpenShift
+        url: /guides/security-saml-openshift
+        description: Learn how to secure applications deployed to WildFly on OpenShift with SAML.
+  - category: MicroProfile
+    cat-id: microprofile
+    guides:
+      - title: Using MicroProfile Config
+        url: /guides/use-microprofile-config
+        description: Discover how to use MicroProfile Config With WildFly.
+#      - title: Using MicroProfile LRA
+#        url: /guides/use-microprofile-lra
+#        description: Discover how to use MicroProfile LRA With WildFly.
+  - category: Automation
+    cat-id: automation
+    guides:
+      - title: Deploying WildFly using Ansible
+        url: /guides/automate-with-ansible
+        description: Learn how to automate WildFly deployments with Ansible.
+

_data/projectfooter.yml

@@ -11,6 +11,8 @@ links:
         url: /get-started
       - page: Github
         url: https://github.com/wildfly/wildfly
+      - page: Guides
+        url: /guides
   - title: Contribute
     subfolderitems:
       - page: Submit a bug

_includes/header.html

@@ -18,6 +18,9 @@
         <li>
             <a target="_blank" href="https://docs.wildfly.org">Docs</a>
         </li>
+        <li>
+          <a href="{{site.baseurl}}/guides/" class="{% if page.url contains '/guides/' %}active{% endif %}">Guides</a>
+        </li>
         <li>
           <a href="{{site.baseurl}}/downloads/" class="{% if page.url contains '/downloads/' %}active{% endif %}">Downloads</a>
         </li>

_includes/index-guides.html

@@ -0,0 +1,19 @@
+<div>
+  <h1 class="title">{{ page.title }}</h1>
+</div>
+
+<div class="guides">
+  <div class="grid-wrapper news-list-blocks">
+    {% for item in site.data["guides"].categories %}
+        <h2 class="grid__item width-12-12" id="{{ item.cat-id }}">{{ item.category }}</h3>
+        {% for guide in item.guides %}
+          <div class="grid__item width-3-12 news-block-item">
+            <div class="post-title">
+              <h4><a href="{{site.baseurl}}{{ guide.url }}">{{ guide.title}}</a></h4>
+              <div class="description">{{ guide.description | markdownify }}</div>
+            </div>
+          </div>
+        {% endfor %}
+    {% endfor %}
+  </div>
+</div>

_layouts/guide.html

@@ -0,0 +1,15 @@
+---
+layout: base
+---
+
+<div class="grid-wrapper guide">
+  <div class="grid__item width-12-12 width-12-12-mobile">
+    <h1 class="text-caps">{{page.title}} {{page.docversion}}</h1>
+  </div>
+  <div class="width-12-12">
+    <div>
+      {{ content }}
+    </div>
+    <div>&lt; <a href="{{ site.baseurl }}/guides">Back to Guides</a></div>
+  </div>
+</div>

_layouts/guides.html

@@ -0,0 +1,5 @@
+---
+layout: base
+---
+
+{% include index-guides.html %}  

_sass/layouts/guides.scss

@@ -0,0 +1,9 @@
+.guide {
+  padding-bottom: 3rem;
+}
+
+.guides {
+  .description {
+    margin: 0 1rem 1rem 1rem;
+  }
+}

assets/css/main.scss

@@ -24,5 +24,6 @@ $content-width: 1000px;
 @import "layouts/error-page";
 @import "layouts/contribute";
 @import "layouts/getstarted";
+@import "layouts/guides";
 @import "layouts/about";
 @import "layouts/post";

getstarted.adoc

@@ -1,6 +1,6 @@
 ---
 layout: getstarted
-title: Get Started with WildFly
+title: Getting Started with WildFly
 permalink: /get-started/
 ---
 :page-liquid:

guides/_includes/_attributes.adoc

@@ -0,0 +1,12 @@
+// WildFly Major version to link to its documentation
+:wildfly-version: 31
+// Minimal version of Maven
+:maven-version: 3.9+
+// Minimal Version of JDK
+:jdk-minimal-version: 11+
+// .
+:toc: right
+// Default time to display in the prerequisites section
+:prerequisites-time: 15
+// OpenShift Container Platform version
+:ocp-version: 4.14

guides/_includes/_prerequisites.adoc

@@ -0,0 +1,8 @@
+[[prerequisites]]
+== Prerequisites
+
+To complete this guide, you need:
+
+* Roughly {prerequisites-time} minutes
+* JDK {jdk-minimal-version} installed with `JAVA_HOME` configured appropriately
+* Apache Maven {maven-version}

guides/_includes/_proc-configure-keycloak.adoc

@@ -0,0 +1,30 @@
+== Configure Keycloak
+
+. Log into the `Keycloak Admin Console`.
+
+. Create a new realm called `myrealm`. For more information, see the Keycloak documentation on how to https://www.keycloak.org/getting-started/getting-started-openshift#_create_a_realm[create a realm].
+
+ifdef::add-role[]
+. Add a role called `User`. This role will be required to access our simple web application. For more information, see the Keycloak documentation on how to https://www.keycloak.org/docs/latest/server_admin/index.html#assigning-permissions-using-roles-and-groups[create a role].
+endif::[]
+
+. Add a new user named `alice`. For more information, see the Keycloak documentation on how to https://www.keycloak.org/getting-started/getting-started-openshift#_create_a_user[create a user].
+
+. Once the new user has been created, set a password for this new user from the `Credentials` tab.
+
+ifdef::add-role[]
+. From the `Role Mapping` tab, assign `alice` the `User` role. For more information, see the Keycloak documentation on how to https://www.keycloak.org/docs/latest/server_admin/index.html#proc-assigning-role-mappings_server_administration_guide[assign a role] to a user.
+endif::[]
+
+. Create a new client as follows:
+* `General Settings`:
+** *Client type* (or *Client Protocol*, depending on your Keycloak version): `OpenID Connect`
+** *Client ID*: `myclient`
+* `Capability config`:
+** *Authentication flow*: `Standard flow`, `Direct access grants`
+* `Login settings`: Leave the fields blank for now.
+
++
+For more information, see the Keycloak documentation on how to https://www.keycloak.org/docs/latest/server_admin/index.html#_oidc_clients[Manage OpenID Connect clients].
+
+. Click `Save` to save the client.

guides/_includes/_proc-follow-build-and-deployment-openshift.adoc

@@ -0,0 +1,17 @@
+The application will now begin to build. This will take a couple of minutes.
+
+The build can be observed using:
+
+[source,bash]
+----
+oc get build -w
+----
+
+Once complete, you can follow the deployment of the application using:
+
+[source,bash]
+----
+oc get deployment oidc-app -w
+----
+
+Alternatively, you can check status directly from the OpenShift web console.

guides/_includes/_proc-install-or-update-helm.adoc

@@ -0,0 +1,14 @@
+If you haven't already installed the WildFly Helm chart, install it:
+
+[source,bash]
+----
+helm repo add wildfly https://docs.wildfly.org/wildfly-charts/
+----
+
+If you've already installed the WildFly Helm Chart, be sure to update it to ensure you have the latest one:
+
+[source,bash]
+----
+helm repo update
+----
+

guides/_includes/_proc-log-into-openshift-cluster.adoc

@@ -0,0 +1,25 @@
+== Log Into the OpenShift Cluster
+
+Before we can deploy our application, we need to log in to an OpenShift cluster. You can log in via the https://docs.openshift.com/container-platform/{ocp-version}/cli_reference/openshift_cli/getting-started-cli.html[OpenShift CLI]:
+
+[source,bash]
+----
+oc login -u myUserName
+----
+
+Alternatively, you can log in using an API token:
+
+[source,bash]
+----
+oc login --token=myToken --server=myServerUrl
+----
+
+You can request the token via the `Copy Login Command` link in the OpenShift web console.
+
+If you don't already have a project created, you can create one using:
+
+[source,bash]
+----
+oc new-project myProjectName
+----
+

guides/_includes/_proc-start-keycloak-openshift.adoc

@@ -0,0 +1,71 @@
+== Start Keycloak
+
+ifndef::saml-auth-method[]
+We will be using Keycloak as our OpenID provider.
+endif::[]
+ifdef::saml-auth-method[]
+We will be using Keycloak as our SAML identity provider.
+endif::[]
+
+To start a Keycloak server in your project on OpenShift, use the following command:
+
+[source,bash]
+----
+oc process -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/latest/openshift/keycloak.yaml \
+    -p KEYCLOAK_ADMIN=admin                    \// <1>
+    -p KEYCLOAK_ADMIN_PASSWORD=admin           \// <2>
+    -p NAMESPACE=<PROJECT_NAME>                \// <3>
+| oc create -f -
+----
+<1> Replace `admin` with the user name you would like to use when accessing the Keycloak Administration Console.
+<2> Replace `admin` with the password you would like to use when accessing the Keycloak Administration Console.
+<3> Replace `<PROJECT_NAME>` with your project name.
+
+After running the above command, you should see the following output:
+
+[source,bash]
+----
+service/keycloak created
+route.route.openshift.io/keycloak created
+Warning: apps.openshift.io/v1 DeploymentConfig is deprecated in v4.14+, unavailable in v4.10000+
+deploymentconfig.apps.openshift.io/keycloak created.
+----
+
+It will take a few minutes for OpenShift to provision the Keycloak pod and its related resources.
+
+You can use the OpenShift CLI or the OpenShift web console, depending on your preference, to check if your Keycloak server has been provisioned.
+
+=== OpenShift CLI
+
+To make sure your Keycloak server has been provisioned using the OpenShift CLI, run:
+
+[source,bash]
+----
+oc get pods
+----
+
+After a little while, check for a message similar to the following message that indicates the pod is ready:
+
+[source,bash]
+----
+NAME                READY     STATUS      RESTARTS   AGE
+keycloak-1-deploy   0/1       Completed   0          1h
+keycloak-1-l9kdx    1/1       Running     0          1h
+----
+
+Once the Keycloak server has been provisioned, use the following command to find the URL for your Keycloak instance's
+Admin Console:
+
+[source,bash]
+----
+KEYCLOAK_URL=https://$(oc get route keycloak --template='{{ .spec.host }}') &&
+echo "" &&
+echo "Keycloak Admin Console:   $KEYCLOAK_URL/admin" &&
+echo ""
+----
+
+=== OpenShift Web Console
+
+To make sure your Keycloak server has been provisioned using the OpenShift web console,
+navigate to the `Topology` view in the `Developer` perspective. You can click on your `keycloak` app
+to check its status. Once it is running, you can click on `Open URL` and then access Keycloak's `Administration Console`.