| Scenario | Recommendation |
|---|---|
| You occasionally use one or two DocOps Lab tools | Use each tool’s own Docker image directly |
| You regularly use multiple DocOps Lab tools | Use DocOps Box (min or max image) |
| Your toolchain uses Ruby and Node/Python tools | Use a DocOps Box max image |
| Your toolchain uses runtimes other than Ruby, Node, or Python | DocOps Box will be partially helpful or unsuitable; advanced users might consider extending the image |
| You are setting up a team documentation environment | Use DocOps Box with a shared .env file in Git |
| You need a CI/CD🔖 pipeline for docs automation | Use DocOps Box live image |
| Criterion | Host Install | DocOps Box |
|---|---|---|
| Setup time (first use) | 45-90 min | ~5 min |
| Reproducibility across machines | High effort | Automatic via config files |
| Team-wide standardization | Requires active coordination, docs | Git-committed .env + docopsbox.yml
|
| Works on Windows | WSL2 + manual setup | WSL2 + Docker |
| IDE integration (VS Code) | Full native | Full via Dev Containers extension |
| Per-project dependencies isolation | As configured per runtime/project | Named volumes 🔖 handled by dxbx
|
| Suitable for CI/CD | Requires environment setup steps | Available via live image |
PATH[🔖](#gloss-path) if not already present
4. Prints instructions to activate `dxbx` in your current terminal session
5. Cleans up by removing the downloaded `dxbx-bootstrap.sh` script
> **TIP:** When any script/command prompts for `[y/N]` or `[Y/n]`, it is requesting approval (`y` for _yes_; `n` for _no_). The capital letter indicates the default selection, so you can just press Enter instead of typing the character to choose the default.
If `${XDG_BIN_HOME}` (or `~/.local/bin` if `XDG_BIN_HOME` is not set) is not yet in your PATH[🔖](#gloss-path), the installer will prompt you to add it automatically; answer `y`.
Then activate it in your current session by running the `export` command it prints, or simply open a new terminal window.
### Step 2: Initialize your project (optional)
> **TIP:** [Skip this step](#step-test-dxbx) if your project is already configured for DocOps Box use. If you do not know, there is no harm in trying.
> **TIP:** It is always advised to stash or commit changes using Git before installing new software in any repository.
>
>
>
> ```
> git stash push -m "Stash before initializing DocOps Box"
> ```
In your project directory:
```
dxbx init
```
This downloads `docopsbox.yml` and `.env` into `.config/`, makes `.devcontainer/devcontainer.json`, prompts for a project slug, and updates `.gitignore` automatically.
**Check for new files**
```
ls -a .config/ .devcontainer/
```
### Step 3: Test dxbx with default image
To test that `dxbx` is working, run this command in your terminal:
```
dxbx ex docops info
```
You should see a nicely formatted readout of available tools and be returned to your host shell prompt.
#What was that?
The second half of the above command (`docops info`) is run inside any DocOps Box container for a readout of tool availability and versions.
The first half (`dxbx ex`) is the command for executing any command in a one-off container, which is created, run, and removed automatically.
### Step 4: Start working
When you need the tools provided by DocOps Box, invoke them _inside_ the container, not on your host system. Typically, you will likely wish to work _inside_ the container interactively, either in VS Code or dedicated terminal app.
Choose whichever entry point suits you; all give you the same environment, and of course you may alternate.
Try `dxbx up` to experience a full interactive shell session inside the container.
Use `dxbx vsc` to open a VS Code window with the containerized environment.
Or use `dxbx ex` to run any command in a fresh container and return to your host prompt immediately.
See the [next section](#usage) for more orientation and explanation of the different ways to work with your new environment.
## Using Your New Environment
As much as DocOps Box tries to abstract away the complexities of Docker, some familiarity with the underlying concepts and commands is helpful for troubleshooting and advanced use.
There are also various ways to invoke these environments in your day-to-day work.
### Understanding Your Shells
The first thing that confuses new users is that you now have _two_ command environments to keep track of: the **host** shell (your normal terminal) and the **container** shell (the Linux environment inside Docker, where your tools actually live and run).
Your computer operating system or shell is the **host** system.
You are virtualizing a purpose-built Linux operating system in a **container** , which exploits your host’s Linux/Unix kernel but is carefully isolated from the rest of your system. Only directories that are mounted into the container are shared between host and container; everything else is separate and protected.
> **NOTE:** If you are using all of this inside WSL2 on Windows, ignore the fact that your Windows OS is also a host. For our purposes, the Linux shell you are running is your _host_, and Windows is your _OS_.
So while you may sometimes have two (or more) command prompts to consider, we will specify the _host_ (where you run `dxbx` commands) or the _container_ (where you run DocOps tools).
Instructions for any third-party Ruby or other CLI utilities (including other DocOps Lab apps) should be performed within a DocOps Box container.
**Mac and Linux users** have two layers:
```
Terminal app → container shell (Zsh)
(host)
```
**Windows users via WSL2** have three layers; you are virtualizing twice:
```
Windows Terminal → WSL2 Linux shell → container shell (Zsh)
(PowerShell) (host)
```
The important thing for **Windows users** : `dxbx` commands are typed in the **WSL2 shell** , not in PowerShell or a Windows Command Prompt. WSL2 _is_ your host for everything that follows.
Table 1. How you get into the container
| Method | How to enter | What happens to your prompt |
|---|---|---|
| VS Code + Dev Containers | Enter dxbx vsc in your host shell.
Or run VS Code through your OS, open a project, Ctrl+Shift+P then select Dev Containers: Reopen in Container if necessary |
Terminal in the Dev Container window runs inside the container. |
| Interactive shell | Enter dxbx up in your host shell |
Your prompt changes to the container shell.
You stay there until you enter exit. |
| Get in and out | Enter dxbx ex followed by any command in your host shell |
Runs the command in a fresh container, prints the output, and removes the container. No change to your prompt. |
| Scenario | Prompt | Command |
|---|---|---|
| Detect PowerShell (Windows only) | PS C:\Users\name> |
You are in PowerShell, not yet in Linux.
Type wsl to enter your WSL2 shell. |
| Detect WSL2 shell (Windows only) | username@hostname:~$ |
You are in WSL2 Linux.
Confirm with uname -a; the output will contain microsoft if you are in WSL2. |
| Exit WSL2 back to PowerShell (Windows only) | username@hostname:~$ |
exit returns you to the PowerShell prompt if you entered WSL2 by typing wsl.
If Windows Terminal opened WSL2 directly as a tab, exit closes the tab instead. |
| Detect container vs host | appuser@work:/workspace% |
hostname prints a short hex string (container ID) if inside the container, or your machine name if on the host. |
| Exit container to host shell | appuser@work:/workspace% |
exit (returns you to your host shell) |
Exit irb to container shell |
irb(main):001> |
exit or Ctrl+D
|
Exit node to container shell |
> |
exit or Ctrl+D
|
Exit python to container shell |
>>> |
exit() or Ctrl+D
|
| Command | Effect |
|---|---|
dxbx stat |
Show container state and volume sizes. |
dxbx wipe --vols |
Remove the container and all per-project dependency volumes (Ruby gems, Node packages, Python venv); preserve shell history. |
dxbx wipe --hist |
Remove dependency volumes and shell history (requires double confirmation). |
dxbx back |
Copy shell history to ~/.local/share/docopslab/dxbx/backups/ before destructive operations. |
dxbx back --restore |
Restore shell history from a backup (append or replace). |
| Form | Selects |
|---|---|
min or max
|
Variant only; context from config |
work or live
|
Context only; variant from config |
max:live, max live
|
Both variant and context |
box-min, box-max
|
Same as min/max (the box- prefix is accepted) |
| Runtime | Manifest file | Install command | Notes |
|---|---|---|---|
| Ruby | Gemfile |
bundle install |
Gems persist in the docops-<slug>-bundle named volume.
Add gems with bundle add <gem> or edit Gemfile directly. |
| Node.js | package.json |
npm install |
Packages persist in the docops-<slug>-node named volume.
Add packages with npm install <pkg> --save. |
| Python | requirements.txt |
pip install -r requirements.txt |
Packages persist in the /opt/venv named volume.
Add packages with pip install <pkg> then freeze: pip freeze > requirements.txt. |
| Variable | Default | Description |
|---|---|---|
PROJECT_SLUG |
see below | Short identifier used to name the per-project gem volume. Set this to something unique across your projects. |
IMAGE_VARIANT |
max |
max (full toolset, adds Node.js and Python) or min (core docs tools: Ruby, Pandoc, Vale, Git).
Shell environment (Zsh vs Bash) is controlled by IMAGE_CONTEXT, not variant. |
IMAGE_CONTEXT |
work |
work (interactive, OhMyZsh) or live (automation, Bash only). |
RUBY_VERSION |
(unset) | Selects a specific Ruby version. Omit (or leave unset) to use the default (3.3). |
IMAGE_REGISTRY |
docopslab |
Docker Hub username or registry prefix for the image. |
| Variable | Use |
|---|---|
HOST_UID |
Override the UID🔖 used for file ownership inside the container.
Set to match id -u on the host if you see permission errors. |
HOST_GID |
Same as above for group ID (id -g). |
IMAGE_REGISTRY |
Override to a private registry or local mirror. |
| Setting | Values | Notes |
|---|---|---|
IMAGE_VARIANT |
max, min
|
min includes Ruby, Bundler, Git, Pandoc, and Vale.
max adds Node.js, Python, and auxiliary tools. |
IMAGE_CONTEXT |
work, live
|
work configures Zsh with Oh My Zsh for interactive daily use;
live uses Bash only, with no interactive enhancements; suited for CI/CD automation. |
RUBY_VERSION |
3.3, 3.4
|
Selects a specific published Ruby version; omit to use the default (3.3).
Setting this appends the version to the context tag: work becomes work-3.4. |
| Tool | Purpose | CLI |
|---|---|---|
| Asciidoctor | Converts .adoc to HTML, PDF, and more |
asciidoctor, asciidoctor-pdf
|
| Kramdown-AsciiDoc | Converts .md to .adoc
|
kramdoc |
| Nokogiri | Parsees and manipulates HTML and XML | nokogiri |
| Tilt | Renders ERB, Liquid, and many more template formats | tilt |
| Pandoc | Document conversion/migration | pandoc |
| Vale CLI | Linting and style checking | vale |
| Redocly CLI | OpenAPI validation and docs generation | redocly |
| Speakeasy CLI | OpenAPI validation and mock servers | speakeasy |
| Vacuum | OpenAPI document manipulation | vacuum |
| LibreOffice CLI tools | Document conversion and manipulation |
soffice, unoserver
|
| jq | Command-line JSON processor | jq |
| yq | Command-line YAML processor | yq |
| Feature | soffice | unoserver |
|---|---|---|
| Document opening/creation | ✅ Full support | ❌ Not directly |
| File conversion | ✅ --convert-to
|
✅ Via server API |
| Print operations | ✅ -p, --pt, --print-to-file
|
❌ Not directly |
| Headless mode | ✅ --headless
|
✅ Implicit (daemon mode) |
| Network/API access | ⚠️ Via --accept
|
✅ Built-in XMLRPC/UNO servers |
| Daemon/background mode | ❌ Limited | ✅ --daemon flag |
| Request limits | ❌ No | ✅ --stop-after
|
| Conversion timeouts | ❌ No | ✅ --conversion-timeout
|
| Logging control | ✅ -f, --verbose, --quiet
|
✅ Same options |
| Port configuration | ❌ Manual via --accept
|
✅ --port, --uno-port
|
| Operation | soffice | unoserver |
|---|---|---|
| Print to PDF | soffice --headless --print-to-file output.pdf input.doc |
❌ |
| Batch processing | Looping soffice calls in a script |
unoserver --daemon + API calls for each file |
| CI/CD pipelines |
soffice invoked in build scripts |
✅ unoserver running as a service, API calls in build scripts |
| Scripted migration | ✅ soffice --convert-to in a script |
unoserver API calls for conversion in a script |
PATH[🔖](#gloss-path) is entirely separate; each invocation independently resolves to whichever install is in scope.
#### Use Everything Natively
If you have decided it is worth the trouble to **install the software directly and locally** , this is your guide to minimizing overhead.
Advice on the few tough choices involved and some maintenance tips are included.
##### Windows Users
It is perfectly possible to run all of these programs and environments, and much more, under **WSL2** on Windows 10 or 11. This is strongly recommended as the way to maintain an optimal, consistent environment. Skip to the [Linux guide](#linux-dependencies) to get started.
---
##### [SIDEBAR] Truly Native Windows Dev Environment
Alternatively, you can get all of this stuff to **run directly on Windows** , though I do not recommend that route.
It has become especially possible to run a proper development environment on Windows 10/11, particularly with the **GitBBash** program that ships with [Git for Windows](https://git-scm.com/download/win).
Ruby has a [Windows installer](https://rubyinstaller.org/downloads/) (choose the latest x64 with Devkit), and it’s supposedly even possible to install [Zsh on Windows](https://dev.to/equiman/zsh-on-windows-without-wsl-4ah9).
It is far from irrational to install everything on Windows, but it’s also probably not optimal, since WSL2 works so well and aligns your system with the absolute vast majority of professional and open-source coders (including anyone with a Mac).
Because this path is not recommended, this guide will not instruct it. However, the links above are a good place to start.
Otherwise, stick with WSL2, and skip to the [Linux guide](#linux-dependencies).
---
##### MacOS Users
Mac users will likely have the fewest steps to get everything installed, especially if you already have Homebrew set up.
> **TIP:** [**Homebrew**](https://brew.sh) is an _essential_ resource on MacOS. It is the equivalent of an official package manager in Linux distributions, managing dependencies and easing the update process. It also keeps you out of Apple’s sphere of control when it comes to installing and maintaining CLI tools and even GUI apps like VS Code, Slack, Postman, LibreOffice, and more.
MacOS **ships with Zsh** , and you are probably already using it. I recommend further customizing with [OhMyZsh](https://ohmyz.sh/), but otherwise no action is needed.
Likewise, MacoS **ships with Git**. Try the command `git --version` to ensure that it is installed.
If not, Homebrew to the rescue!
```
brew install git
```
Even though OSX comes with **Ruby** pre-installed, it is _not properly set up for our purposes_, and you will likely see lots of errors and be forced to use the `sudo` command prefix to perform commands as superuser, which is not advised.
Instead, use rbenv or another [Ruby management platform](#native-ruby), as instructed below.
##### Linux Users (Including WSL)
Install any packages _except Ruby_ using your package manager.
For example, on Ubuntu- or Debian-based distributions, you can install Zsh and Git with:
```
sudo apt-get install zsh git
```
Your distribution likely does not come with Ruby installed, and we do not advise using your package manager to install it. This is likewise true for [Node.js](#native-nodejs).
Most Linux distributions ship with Python 3 installed. See the section in this guide on [Python](#native-python) for instructions on managing Python versions if needed.
#### Use a Ruby management system
Even if your operating system already has Ruby installed, you should reinstall with a version manager. This is **especially the case with MacOS** , which has weird permissions issues with its native installation.
My personal version manager of choice is [rbenv](https://github.com/rbenv/rbenv). I have never seen rbenv installation fail using their recommended procedure.
If you are feeling adventurous, rbenv’s maintainer keeps [this list of alternative Ruby managers](https://github.com/rbenv/rbenv/wiki/Comparison-of-version-managers), with good things to say about several of them. I may get around to experimenting with them, but for now my instructions will assume rbenv.
---
##### [SIDEBAR] So, Which Ruby Version?
The default version in the accompanying Docker image is 3.3, which is well-supported across the gem ecosystem. The latest supported version (3.4) can also be used; choose it for new projects.
With rbenv or an equivalent version manager you can keep multiple versions on hand for projects with divergent dependencies. In that case, set different local versions:
```
rbenv install 3.3
rbenv install 3.4
rbenv global 3.4
cd project-a
rbenv local 3.3
cd ../project-b
rbenv local 3.4
```
All executions of `ruby`, `bundle exec`, etc. will use the locally appropriate Ruby stack. This approach is compatible with the DocOps Box/`dxbx` method, which uses the right Docker image per project.
---
#### Add Ruby gems globally
Once Ruby is installed, you can install any gems you like globally on your host system.
The ones that ship with DocOps Box `work` images are:
```
gem install asciidoctor kramdown-asciidoc nokogiri tilt
```
If you decide not to use the Docker image, you may still wish to use the optional software included in the image. Here we instruct setting up the other runtimes and utilities that are included in the DocOps Box Docker image.
#### Node.js
Whether you use Node.js as a main runtime environment or not, you will sooner or later surely need the Node Version Manager (nvm) application to manage Javascript assets.
Both nvm and Node.js are best installed using their [platform- and installer-specific documentation](https://nodejs.org/en/download/package-manager). Be sure to choose your platform (Linux or MacOS). For the rest, leave default settings, unless you have reason to do otherwise.
> **NOTE:** Windows users should definitely install these resources on their WSL2 hosting instance, even though there are Windows versions available.
As of now, the Version 24 line is most widely used, including by the DocOps Box images.
If you need multiple versions of Node.js, that’s what nvm is for. Just use commands like nvm install 22 and nvm use 22 to switch between versions.
#### Python
Most Linux and MacOS distributions come with Python 3 pre-installed, including the Ubuntu and Fedora distributions that work with WSL2 on Windows.
In my experience, the pre-installed Python versions are usually sufficient for the tools we tend to use for docs-as-code. If you need to install or manage Python versions, the [pyenv](https://realpython.com/intro-to-pyenv/) tool is a good choice, with installation instructions for all platforms.
Similarly to Ruby on MacOS, the pre-installed Python on Linux may have permissions issues that make it difficult to work with.
#### Pandoc
Even if Pandoc is not central to your documentation toolchain, sooner or later it will be just the right tool. It can be especially useful during one-time migrations from one source format to another.
> **NOTE:** It may be more sensible to install Pandoc directly on Windows in addition to WSL2, just for ease of access.
Pandoc maintains [downloads and installation instructions](https://pandoc.org/installing.html) for all operating systems.
#### Vale
Vale is a prose linter that can be configured with style guides to enforce writing standards.
Follow Vale’s [installation instructions](https://vale.sh/docs/install) for your platform to set it up natively.
#### LibreOffice CLI
To take advantage of any of LibreOffice’s document manipulation tools or extensions, install the CLI tools.
Support for LibreOffice functionality on the command line comes in two separate tools: [`soffice`](https://www.systutorials.com/linux-manual-page-1-soffice/) and [`unoconv/unoserver`](https://github.com/unoconv/unoserver/).
Unfortunately, installation of these tools is complicated. Look to the DocOps Box `Dockerfile` for reference, but novice users may need help with this step. The `unoserver` command relies on Python, and the `soffice` command comes with LibreOffice utilities and may already be available or may need multi-step installation.
#### Redocly CLI
Redocly CLI is a powerful tool for managing OpenAPI documents, including generating API references from them. It runs on your Node.js runtime, so you can install it with npm:
```
npm install -g @redocly/cli
```
#### Other environment customizations
The DocOps Box `work` images include a handful of quality-of-life tweaks beyond the default Zsh/OhMyZsh setup.
If you are running these tools on your host, you can reproduce any of these you find useful.