--- ---

Dev-tooling Setup

Environment and Bootstrapping for new DocOpsLab project codebases or establishing a complete dev environment

This guide pertains to the docopslab-dev environment. For complete documentation, see the project’s README.

The environment described and provided here is not optimized for DocOps Lab applications used in third-party projects. For your own applications of DocOps Labs products like ReleaseHx and Issuer, see DocOps Box for a full-featured docs-focused workspace, runtime, and production environment.

If this is your first time using docopslab-dev on a given workstation, you will need to ensure the prerequisites are met.

If you have the prerequisites and are just getting started with a given DocOps Lab project, you should be ready after Initialize or Sync.

If you are initializing docopslab-dev in an new project, you will also need to initialize the environment.

Prerequisites

There are three ways to prepare the necessary dependencies and runtimes.

If you are already a Ruby user, Option 1 is likely for you. Otherwise, Option 2 is strongly recommended, at least for getting started quickly.

Option 1: Native Installations

Ruby & Bundler

  • Ruby 3.2+ with Bundler installed natively

  • gem 'docopslab-dev' in `Gemfile

  • All Ruby gems managed via bundle install

Vale

  • brew install vale (macOS)

  • apt install vale (Ubuntu/Debian)

  • dnf install vale (Fedora)

  • If not installed, vale operations will fallback to Docker execution

Asciidoctor (to support Vale)

  • installed globally

    • gem install asciidoctor or

    • npm i -g asciidoctor or

    • natively installed through your system’s package manager

  • Test with asciidoctor --version

ShellCheck

  • brew install shellcheck (macOS)

  • apt install shellcheck (Ubuntu/Debian)

  • dnf install shellcheck (Fedora)

  • If not installed, shellcheck operations will fallback to Docker execution

actionlint

  • brew install actionlint (macOS)`

  • go install github.com/rhysd/actionlint/cmd/actionlint@latest (Go 1.16 or later)

  • Otherwise see install guide.

  • If not installed, actionlint operations will fallback to Docker execution

Option 2: Full Docker Environment

The docopslab/dev image provides a complete development environment with Ruby, Vale, and all linting tools pre-installed.

Add an alias to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make Docker usage easier:

alias lab-dev='docker run -it --rm -v "$(pwd):/workspace" docopslab/dev'

Now lab-dev replaces the full Docker command and causes insertion of bundle exec for rake or labdev: commands.

Option 3: Ruby with Docker fallback

  • Ruby & Bundler + Gemfile as in Option 1

  • Vale and other non-Ruby services run via Docker if not installed locally as in Option 2

  • All labdev: rake tasks that use non-Ruby dependencies will attempt native execution first, then fall back to Docker if the tool is not found or is found to be the wrong version.

Initialize or Sync

Once dependencies are installed, the development environment may need to be initialized and must be synced, between your local instance and source assets.

Assuming you are not initializing a new project, you can skip to Environment Synchronization.

Project Initialization

If you are introducing docopslab-dev to an existing project, you first need to integrate and initialize it.

  1. Add docopslab-dev to the project’s Gemfile.

    group :development do
  gem 'docopslab-dev'
end

  2. Install the gem.

    bundle install

  3. Add require 'docopslab/dev' to the top of the project’s Rakefile.

    A project lacking any configuration files can now be initialized.

  4. Use bundle exec rake labdev:check to ensure the project environment is aligned.

  5. Initialize the development environment

    bundle exec rake labdev:init:all

The init task creates .config/docopslab-dev.yml and default project configs for all tools. This file should be Git tracked for the project.

Initialization also performs environment synchronization.

Environment Synchronization

This process is part of the init operation, but on its own it ensures local configs and assets are up to date with their source templates.

Install the dependencies (if not done already)
bundle install
Sync configuration files
bundle exec rake labdev:sync:all
For configuration details, see DocOps Lab Dev-tooling Configuration.
See DocOps Lab Dev-tooling Usage for operational details.