Skip to content

Setting up local website development

Jump to bottom
natalie-bernhard edited this page Jan 25, 2023 · 57 revisions

Setting up environment

Also can be used to setup a local development environment when making changes to openliberty.io

You will need the following tools installed on your system

Clone the website code

  1. git clone [email protected]:OpenLiberty/openliberty.io.git
  2. cd openliberty.io

Install ruby libraries used by the website by running gem commands to install these libraries

Note If you run into issues installing gems, it is recommended to get RVM for Ruby management on your local machine. Run \curl -sSL https://get.rvm.io | bash -s stable --ruby to install RVM and then run rvm install 2.5.7 and rvm use 2.5.7 --default to use the version of Ruby that the website uses.

  1. gem install jekyll -v 3.8.6
  2. gem install jekyll-assets -v 2.4.0
  3. gem install bundler jekyll-feed jekyll-asciidoc jekyll-include-cache coderay uglifier octopress-minify-html octokit
  4. pushd gems/ol-target-blank
  5. gem build ol-target-blank.gemspec
  6. gem install ol-target-blank-0.0.1.gem
  7. popd

Note: You can find these commands in the build scripts here: https://github.com/OpenLiberty/openliberty.io/blob/prod/scripts/build/ruby_install.sh https://github.com/OpenLiberty/openliberty.io/blob/prod/scripts/build/jekyll.sh

(Optional) Turn off JavaScript/CSS/HTML minification for performance

In openliberty.io/src/main/content/_config.yml set these values to false, css, js, minify_html. The result should look like

assets:
  compress:
    css: false
    js: false

env: production
minify_html: false

Run the Jekyll server locally

While the Jekyll server is running...

You can make changes to index.html. When you make changes, monitor your terminal for messages saying Regenerating: 1 file(s) changed at 2018-03-16 12:04:56 ...done in 13.638151 seconds. Once it's done updating, view your changes on http://localhost:4000/.

Example of starting Jekyll and making an *.adoc change

~/work/sandboxes/openliberty.io/src/main/content  (blogSpacingAltText)# jekyll s --drafts
Configuration file: ~/work/sandboxes/openliberty.io/src/main/content/_config.yml
            Source: ~/work/sandboxes/openliberty.io/src/main/content
       Destination: ~/work/sandboxes/openliberty.io/src/main/content/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 23.506 seconds.
 Auto-regeneration: enabled for '~/work/sandboxes/openliberty.io/src/main/content'
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.
      Regenerating: 1 file(s) changed at 2018-03-16 12:04:56

To clone guides:

  1. First, ensure ruby is installed on your machine
  2. Run ruby ./scripts/build/clone_guides.rb

To clone docs:

To build Docs locally (separate from Jekyll)

  1. Install node version v12.18.3 nvm install 12.18.3 on your system (if you have multiple nodes and already installed node 12.18.3, run nvm use 12.18.3, check current node version node -v should return v12.18.3)
  2. ./scripts/build_antora_dev.sh --update (note: if you want to run locally as a production env then do PROD_SITE=true ./scripts/build_antora_dev.sh --update)
  3. the above script run for about 30', at the end you would see something like
Starting up http-server, serving src/main/content/docs/build/site

http-server version: 14.1.0

http-server settings: 
CORS: disabled
Cache: 3600 seconds
Connection Timeout: 120 seconds
Directory Listings: visible
AutoIndex: visible
Serve GZIP Files: false
Serve Brotli Files: false
Default File Extension: none

Available on:
  http://127.0.0.1:8080
  http://192.168.86.249:8080
  http://9.77.141.183:8080
Hit CTRL-C to stop the server
  1. Go to http://localhost:8080/docs/22.0.0.1 to see docs page.

Note To clean out caching data, delete build & public folders under src/main/content/antora_ui/

To debug the back-end java code that run on the server side locally (src/main/content/java/io/openliberty/website)

  1. To build the openliberty.war, under the root of your local openliberty.io git directory run:
   mkdir -p target/jekyll-webapp
   jekyll build --future --source src/main/content --destination target/jekyll-webapp
   mvn -B package
  1. If you don't already have a wlp driver, download and unzip the latest wlp driver from https://openliberty.io/start from All GA Features
  2. cd to wlp/bin, create defaultServer ./server create defaultServer
  3. Use the following server.xml, update the webApplication location to point to your openliberty.war location:
   <featureManager>
        <feature>jaxrs-2.1</feature>
        <feature>jsonb-1.0</feature>
        <feature>concurrent-1.0</feature>
        <feature>cdi-2.0</feature>
        <feature>mpRestClient-1.3</feature>
        <feature>mpConfig-1.4</feature>
        <feature>transportSecurity-1.0</feature>
        <feature>mpOpenAPI-1.0</feature>
        <feature>beanValidation-2.0</feature>
        <feature>webCache-1.0</feature>
    </featureManager>

    <!-- To access this server from a remote client add a host attribute to the following element, e.g. host="*" -->
    <httpEndpoint id="defaultHttpEndpoint"
                  httpPort="9080"``
                  httpsPort="9443" />

    <!-- Automatically expand WAR files and EAR files -->
    <applicationManager autoExpand="true"/>

    <!-- Default SSL configuration enables trust for default certificates from the Java runtime --> 
    <ssl id="defaultSSLConfig" trustDefaultCerts="true" />

    <cdi12 enableImplicitBeanArchives="false"/>

    <webApplication contextRoot="/" id="openlibertyio" location="/Users/aknguyen/Liberty/libertyGit/openliberty.io/target/openliberty.war"/>

    <!-- <webApplication contextRoot="/" id="start" location="/Users/aknguyen/libertyGit/start.openliberty.io/target/openliberty-starter-1.0-SNAPSHOT.war"/> -->

    <logging traceSpecification="io.openliberty.website.starter.*=all"></logging>

    <keyStore id="defaultKeyStore"/>
  1. Start defaultServer, run ./server run defaultServer
  2. Go to https://localhost:9443 to see the local openliberty.io site
  3. To view the json data https://localhost:9443/api/builds/data
  4. To run junit test, under the root of your local openliberty.io git directory run mvn integration-test

Note You might run into some certificate issue then create retrieve-cert.sh file

#!/bin/sh
#
# usage: retrieve-cert.sh remote.host.name [port]
#
REMHOST=$1
REMPORT=${2:-443}
echo |\
openssl s_client -connect ${REMHOST}:${REMPORT} 2>&1 |\
sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'

then run

./retrieve-cert.sh public.dhe.ibm.com > dhe.pem
keytool -import -file dhe.pem -alias dheserver -keystore trust.jks -storepass Liberty

copy the trust.jks to /wlp/usr/servers/defaultServer/resources/security

To build open liberty site to support multiple languages using Jekyll multiple language plugin locally

  1. Clone the latest website code

  2. Latest code has the jekyll-multiple-languages-plugin included in their respective dependency files to support multiple languages

  3. In src/main/content/_config.yml file it has key called languages. languages: ["en"] If the site need to support non-english languages say Japanese, German then add short format of language names in languages array as languages: ["en","jp","de"]

  4. NLS folder is created to support externalized string in html. Right now we have file to support English - src/main/content/_i18n/en.yml. If we need to support multiple languages say Japanese, German respective yml should be created as src/main/content/_i18n/jp.yml, src/main/content/_i18n/de.yml The file name should be exactly same as the name entered in languages section of (src/main/content/_config.yml)

  5. Build site locally using DRAFT_SITE=true ./scripts/build/build.sh

  6. It generates target/jekyll-webapp (has English folder and files) as root folder target/jekyll-webapp/jp (Japanese folder and files) target/jekyll-webapp/de (German folder and files)

Other:

  1. Antora templates https://docs.antora.org/antora-ui-default/templates
  2. Handlebars https://handlebarsjs.com

If you need any help setting up your local environment, please open an issue with steps you followed and errors seen in the console (https://github.com/OpenLiberty/openliberty.io/issues/new).

Clone this wiki locally