Summary

Publishing updates to the project website involves committing changes to defined Apache Software Foundation infrastructure repositories and branches.

Staging

Apache Infrastructure supports automated staging deployments based on a configurable branch of a the project website repository.

The Apache NiFi staging website is available at the following location:

Staging Repository Configuration

Apache Infrastructure enables staging website updates based on the .asf.yaml repository configuration. Apache Infrastructure PyPubSub reads the YAML configuration and takes action based on the provided settings.

The following YAML configuration section enables automatic website updates to staging based on the configured branch, specified in the whoami field:

staging:
  profile: ~
  whoami: asf-staging

The staging configuration defines the asf-staging branch as the source for the website content to be deployed.

The profile field specifies the tilde character to indicate that the branch should be deployed to the default profile instead of an alternative profile location.

Staging Build Workflow

The project website repository uses GitHub Actions to build and push changes to the configured staging branch.

The main-staging branch contains for the source files and build workflow.

The build.yml workflow configuration includes the following steps to be executed on a push to the source branch:

  1. Checkout source branch: main-staging
  2. Checkout destination branch to publishing directory: asf-staging
  3. Install Hugo
  4. Build source and write content to publishing directory
  5. Commit changes to destination branch
  6. Push changes to destination branch

Production

Apache Infrastructure supports automated production deployments based on a configurable branch of the project website repository.

The Apache NiFi production website is available at the following location:

Production Repository Configuration

Apache Infrastructure enables production website updates based on the .asf.yaml repository configuration. Apache Infrastructure PyPubSub reads the YAML configuration and takes action based on the provided settings.

The following YAML configuration section enables automatic website updates to production based on the configured branch, specified in the whoami field:

publish:
  whoami: asf-site

The publish configuration defines the asf-site branch as the source for the website content to be deployed.

Production Build Workflow

The project website repository uses GitHub Actions to build and push changes to the configured staging branch.

The main branch contains for the source files and build workflow.

The build.yml workflow configuration includes the following steps to be executed on a push to the source branch:

  1. Checkout source branch: main
  2. Checkout destination branch to publishing directory: asf-site
  3. Install Hugo
  4. Build source and write content to publishing directory
  5. Commit changes to destination branch
  6. Push changes to destination branch

Generated Documentation

Apache NiFi and Apache NiFi Registry generate documentation based on available components and documentation sources. Publishing generated documentation involves several steps outside of the Apache NiFi site build workflow.

Publishing Process

Publishing updates to generated documentation involves the following steps:

  1. Start Apache NiFi or Apache NiFi Registry with standard HTTP and without TLS
  2. Clone Git branch containing compiled website files
  3. Delete existing documentation directories from cloned Git branch
  4. Mirror documentation from running application
  5. Move updated documentation to cloned Git branch
  6. Add changed files to Git version control
  7. Push changes to Git branch

Publishing Commands

The following script provides an example of command necessary to follow the publishing process for generated documentation.

The SERVICE_LOCATION indicates the server and port of the running instance of Apache NiFi or Apache NiFi Registry. The value should be localhost:8080 for NiFi or localhost:18080 for NiFi Registry.

The GIT_SITE_BRANCH indicates the Git branch containing deployed website files. The asf-staging branch contains the staging site, the asf-site branch contains the production site.

The RELATIVE_SERVICE_PATH indicates the base path for retrieving documentation. The value should be nifi for NiFi or nifi-registry for NiFi Registry.

Running the following script executes the necessary steps except for pushing the changes.

#!/bin/sh

SERVICE_LOCATION="localhost:8080"
GIT_SITE_BRANCH=asf-staging
RELATIVE_SERVICE_PATH=nifi

RELATIVE_DOCS_PATH=$RELATIVE_SERVICE_PATH-docs
SITE_DIR=nifi-site
LOCAL_DOCS_DIR=$SITE_DIR/docs

rm -rf $SITE_DIR

# Clone Git branch containing compiled website files
git clone https://github.com/apache/nifi-site.git -b $GIT_SITE_BRANCH

# Delete existing documentation directories from cloned Git branch
rm -rf ${LOCAL_DOCS_DIR}/${RELATIVE_SERVICE_PATH}
rm -rf ${LOCAL_DOCS_DIR}/${RELATIVE_DOCS_PATH}

# Mirror documentation from running application
wget -prk http://${SERVICE_LOCATION}/${RELATIVE_DOCS_PATH}/documentation

# Move updated documentation to cloned Git branch
mv ${SERVICE_LOCATION}/${RELATIVE_DOCS_PATH} $LOCAL_DOCS_DIR
mv ${SERVICE_LOCATION}/${RELATIVE_SERVICE_PATH} $LOCAL_DOCS_DIR
rm -rf ${SERVICE_LOCATION}
mv ${LOCAL_DOCS_DIR}/${RELATIVE_DOCS_PATH}/documentation ${LOCAL_DOCS_DIR}/${RELATIVE_DOCS_PATH}/index.html

# Add changed files to Git version control
cd $SITE_DIR
git add docs

After running the script, the following Git commands can be used to check the status and push the changes.

cd nifi-site
git commit -m "Published documentation for NiFi 1.0.0"
git push

References

  • No labels