Operate First Website

This repository contains some content and the code to build operate-first.cloud. It is based on Gatsby and can be deployed to OpenShift or GitHub Pages.

Adding Content

We want to make it really easy for content contributors to add their material to the website. Content can be added directly to this repository or from a remote repository. The latter is the preferred way, so that content creators dont need to duplicate their content into this repository. This site is merely an aggregator.

Remote Content

Prefer adding content remotely to this website. This means, your content is in another git repository and you configure this site to pull in the content. You'll only add entries to the sitemap, so that your content can be accessed via links.

Add a gatsby-source-git section to gatsby-config.js.

{
  resolve: `gatsby-source-git`,
  options: {
    name: `data-science/ocp-ci-analysis`,
    remote: `https://github.com/aicoe-aiops/ocp-ci-analysis.git`,
    patterns: [`**/*.md`, `**/*.ipynb`],
  }
},

The name for the plugin will be the prefix for URLs generated from that repository. In the following example, all Markdown and JupyterNotebook files will be rendered as pages under the /data-science/ocp-ci-analysis path.

The notebooks/data-sources/TestGrid/testgrid_EDA.ipynb Notebook will be rendered at /data-science/ocp-ci-analysis/notebooks/data-sources/TestGrid/testgrid_EDA.ipynb.

Local Content

All local content goes into the /content folder. All files will be available as pages, starting from the root URL of the site.

For example, to add content locally to the blueprints category, create a document located at content/blueprints/my_doc.md.

Supported File Types

Files formatted as

Markdown

Markdown files can be prefixed with frontmatter.

See /content/examples/markdown.md rendered here

---
title: My Document
description: My Document Description
---

# Content goes here

valid markdown

To add videos to Markdown follow the instructions given in /content/examples/markdown.md#add-videos

JupyterNotebook

Any file with the .ipynb extension will be rendered as HTML. This is done via the gatsby-transformer-ipynb.

See /content/examples/jupyter_notebook.ipynb rendered here

MDX

Similar to Markdown, but you can add React Components, which basically extend HTML. E.g. you can embedd a JupyterNotebook into the MDX file.

See /content/examples/mdx.mdx rendered here

---
title: My MDX
description: MarkdownX
---

This is how I include a Notebook:

<JupyterNotebook path="jupyter_notebook.ipynb"/>

Linking

All links should be added as relative links, i.e. they should not start with a /. If you link to another document in your own content repository, then a relative link will work when the content is rendered at GitHub and it will work in the gatsby site.

index.md and README.md files will be treated as index files. Their name will be stripped from the URL. E.g. /folder/README.md would result in /folder/

Site structure

Content will be added to one of the four categories on this website:

data-science: Examples of data science projects for the data science users that want to learn about data science on ODH.
users: Documentation for all users of ODH. Access details of various deployed ODH components.
operations: Documentation pertaining to Operate First operation procedures.
blueprints: Generic information that can be applied to other projects as well.

Configuring Table of Contents

Whether adding content remotely, or locally, the content needs to be added to the vertical navigation bar on the left and will belong to one of the four categories.

The config directory contains category.yaml files for each category eg: blueprints.yaml for the Blueprints category and this file will contain the table of content navigation items for each document that you add.

- label: The Navigation Item
  href: /the/url/to/the/page

Following is an example of 2 level hierarchy from a repo, for cases where you have to add more than one document from a repository as remote content.

- label: Continuous Delivery
  links:
    - label: (Opinionated) Continuous Delivery
      href: /blueprints/continuous-delivery/docs/continuous_delivery
    - label: Setting up Source Code Operations
      href: /blueprints/continuous-delivery/docs/setup_source_operations

Local Development

You can run the app locally to preview your changes. In terminal:

make dev

If you have problems, run make dev-clean

Previewing your changes on GitHub pages

When previewing your changes on a fork.

First, enable github pages to use the gh-pages branch from root.

Make sure to push your changes to your branch on the fork.

Then, from your branch manually build and push.

make gh-pages-fork

Now you can view your work on https://githubuserid.github.io/operate-first.github.io

Previewing multiple PRs on GitHub pages

If you've set up to preview the site on your personal GitHub pages, like the above, you can also preview multiple PR branches from your fork under separate paths. For example, for a branch named my-branch, would deploy under a subpath of the same name.

From your branch manually build and push.

make gh-pages-branch

Now you can view your work on https://githubuserid.github.io/operate-first.github.io/my-branch

Manual Site Deployment (Production GitHub Pages)

CI should deploy to GitHub pages automatically, but to manually redeploy

make gh-pages

Building the site in a container

Customize your .env file similar to .env.default(.env.default)

Building a containerized image

Customize .env file to image and source information as desired. npm and the s2i command line tool is required. https://github.com/openshift/source-to-image

IMAGE_REPOSITORY=quay.io/my-org/operate-first-app:latest
SOURCE_REPOSITORY_URL=git@github.com:my-org/operate-first.github.io.git
SOURCE_REPOSITORY_REF=my-branch

make build

Pushing the container image

Customize .env file to image information and container builder.

CONTAINER_BUILDER=docker
IMAGE_REPOSITORY=quay.io/my-org/odh-dashboard:latest

make push

Deploying to OpenShift

Customize .env file for deployment information. Required. oc command line tool is required.

OC_URL=https://api.my-host:6443
OC_PROJECT=operate-first
# user and password login
OC_USER=kubeadmin
OC_PASSWORD=my_password

OC_URL=https://api.my-host:6443
OC_PROJECT=operate-first
# token login
OC_TOKEN=my_token

Modify the image repository in the deployment config deployment.yaml present in scripts/templates/base to fetch the latest image from the location you pushed the container image to in the previous step.

Modify the following line to reflect the image repository you pushed it to.

image: quay.io/cfchase/operate-first-app:latest

Run:

make deploy

Shreyanand / operate-first.github.io