For production use, deploy TechDocs by building documentation in CI/CD, publishing to external storage such as AWS S3, and configuring read-only mode. You can automate this workflow using GitHub Actions to generate and publish TechDocs when users update documentation files.
Before you begin
- The TechDocs plugin is enabled and configured on your Red Hat Developer Hub instance.
- Your organization has documentation files stored in a remote repository.
- You have an mkdocs.yaml file located in the root directory of your repository.
- You have the
catalog.entity.create and catalog.location.create permissions to import documentation into TechDocs from a remote repository.
- You have an AWS S3 bucket to store your TechDocs sites.
- Minimal IAM Policies are configured for your S3 bucket, granting both Write and Read access.
- An administrator has created an IAM User, attached the necessary policy, and generated an access key in the AWS console.
Procedure
-
Set up the GitHub Actions workflow.
-
On GitHub, create a fork of the RHDH TechDocs Pipeline repository.
Note
The rhdh-techdocs-pipeline repository contains a generate-and-publish-techdocs.yaml workflow that automatically generates TechDocs from the docs folder and publishes them to an Amazon S3 bucket.
-
Use the GitHub GUI to make sure that all of the permissions required to run the workflow are enabled.
-
Add the Repository secrets required to connect the workflow to your AWS account, for example,
TECHDOCS_S3_BUCKET_NAME, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION.
Note
The default mkdocs.yaml file in the rhdh-techdocs-pipeline workflow installs the techdocs-core and minify plugins.
-
Optional: Customize the default structure or files of the
rhdh-techdocs-pipeline repository to meet the needs of your organization.
-
Optional: Add other
mkdocs plugins that you want to use by adding the name of the plugins to the plugins section of the mkdocs.yaml file and to the steps.name: install mkdocs and mkdocs plugins section of the generate-and-publish-techdocs.yaml file.
-
. In the navigation menu of the OpenShift Container Platform console, click ConfigMaps and select your RHDH
app-config.yaml file.
-
Update the
app-config.yaml file to enable your Amazon S3 bucket to serve TechDocs to your RHDH instance. For example:
techdocs:
builder: external
publisher:
type: awsS3
awsS3:
bucketName: $AWS_S3_BUCKET_NAME}
accountId: $AWS_ACCOUNT_ID}
region: $AWS_REGION}
aws:
accounts:
- accountId: $AWS_ACCOUNT_ID}
accessKeyId: $AWS_ACCESS_KEY_ID}
secretAccessKey: $AWS_SECRET_ACCESS_KEY}
catalog:
locations:
- type: url
target: https://github.com/<your_org>/rhdh-techdocs-pipeline/blob/main/catalog-info.yaml
-
Click Save.
-
In the navigation menu of the OpenShift Container Platform console, click Topology and restart the pod.
Note
Changes to the docs folder or the mkdocs.yaml file trigger the rhdh-techdocs-pipeline workflow to run. After the rhdh-techdocs-pipeline workflow runs successfully, the generated TechDocs are uploaded to your Amazon S3 bucket.
Results
- Go to your RHDH instance and click Docs to see the TechDocs served from your Amazon S3 bucket.