--- ---

Deployment Setup (General)

Initial preparation for publishing gems, Docker images, and documentation sites

This guide describes the new-project setup for deployment platforms for release artifacts like executables, Docker images, and product documentation sites.

Prerequisites

Required Credentials

Use environment variables to store sensitive credentials securely. These credentials are only needed during the release process, not the development phase.

  • RubyGems API Key

  • Docker Hub Credentials

    • Organization: docopslab

    • DockerHub account with write permissions for docopslab images

    • Set as: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN

  • GitHub Token (some projects only)

    • Scope: repo

    • Set as: DOCOPSLAB_GITHUB_TOKEN or GITHUB_TOKEN

Ruby Gem Publishing

  1. Configure GitHub repository secrets with RUBYGEMS_AUTH_TOKEN.

  2. Ensure gemspec includes spec.metadata['rubygems_mfa_required'] = 'true'.

Docker Image Publishing

  1. Create repository on Docker Hub under docopslab organization.

  2. Create repository on GitHub Container Registry.

  3. Configure GitHub repository secrets with DOCKERHUB_USERNAME and DOCKERHUB_TOKEN.

Documentation Site Publishing

Most DocOps Lab projects have their own documentation sites, also built with Jekyll and AsciiDoc, often including YARD for Ruby API reference generation.

For less-formalized projects, documentation is restricted to README.adoc and other *.adoc files. These are hosted as GitHub Pages sites from their respective repositories, but using a consistent URL structure centered on the docopslab.org domain hosted here.

The URL structure is as follows:

Project landing page

https://<project>.docopslab.org/

At a minimum, this should be a subset of the README.adoc file.

Product user docs

https://<project>.docopslab.org/docs/

Product developer docs

https://.docopslab.org/docs/api/(/)

The final <apiname> directory is only applicable when the product contains multiple distinct APIs.

GH Pages configuration for these sites enables deployment by way of a clean gh-pages branch containing only generated documentation artifacts and the CNAME file.

Setup Steps

  1. Create docs/CNAME file containing <project>.docopslab.org.

  2. Go to repository Settings → Pages.

  3. Set Source to "GitHub Actions".

  4. Ensure custom domain is set to <project>.docopslab.org.

  5. Verify DNS configuration points to GitHub Pages.