okf-gem · docs
Start here

Run with Docker

The whole toolkit, no Ruby on the host.

When to use it

The gem is pure Ruby and runs on the Ruby your OS already ships, so gem install okf is the shortest path on most machines. Reach for the image when the Ruby is not yours to control: a CI job on a stack you would rather not add a toolchain to, a Kubernetes step, a reviewer's laptop, or any box where pulling an image beats installing a gem. The image carries the same CLI, so every verb behaves the same way. Run okf with Docker is the full walkthrough.

Pull and run

The image lives at ghcr.io/serradura/okf and mounts your bundle at /data. Point any read verb at the mount:

docker run --rm -v "$PWD:/data" ghcr.io/serradura/okf validate .
docker run --rm -v "$PWD:/data" ghcr.io/serradura/okf lint .
docker run --rm -v "$PWD:/data" ghcr.io/serradura/okf search . "graph server"

--rm cleans up the container after each run, and -v "$PWD:/data" maps the current directory onto /data, the image's working directory, so the bundle is just .. The whole CLI is the entrypoint, so whatever you would type after okf you type after the image name.

Images are published for linux/amd64 and linux/arm64. :latest tracks the newest release; pin a tag like :1.9.0 when you want CI to stay put.

Serve the graph

The graph server needs two extra flags in a container. It binds to 127.0.0.1 by default, which nothing outside the container can reach, so bind it to 0.0.0.0 and publish the port:

docker run --rm -v "$PWD:/data" -p 8808:8808 \
  ghcr.io/serradura/okf server . --bind 0.0.0.0

Then open http://127.0.0.1:8808 on the host. The server reads bodies from disk on each request, so edits to the mounted bundle show on the next click with no restart. Ctrl-C, or docker stop, shuts it down cleanly.

Mounts and exit codes

A read-only mount is enough for every command above (validate, lint, search, index, the views, and server all only read), so you can harden the run with -v "$PWD:/data:ro". The one verb that writes is okf skill <dest>, which needs a writable mount.

Exit codes are unchanged from the CLI, so the image drops straight into a pipeline: 0 success, 1 a non-conformant bundle or a crossed lint --fail-on threshold, 2 a usage error. Gating a job on the image is the same contract as gating on the gem.

Skip the prefix: install okf

Typing the full docker run line every time gets old. The installer drops a tiny script named okf on your PATH, so the image takes the exact CLI interface: okf validate ., okf lint ., okf server .. Because the command is okf, the agent skill and everything else that calls okf keep working, with no Docker to think about. It mounts your directory at /data, and for server it publishes the port and adds --bind 0.0.0.0, so nothing extra to remember.

Install it with one line (do this only on a machine without the gem, since it adds an okf command):

curl -fsSL https://docker.okfgem.com/install.sh | sh

Or do it by hand, which is the same three steps the installer runs:

curl -fsSL https://docker.okfgem.com/okf -o /usr/local/bin/okf
chmod +x /usr/local/bin/okf
okf --version

Then every verb reads like the CLI:

okf validate .
okf server .            # port published and bound for you
okf search . "graph server"

The command runs ghcr.io/serradura/okf:latest by default; set OKF_IMAGE to pin a version. Docker still does the work, so the same privacy and offline story holds.

On Windows

The image is Linux, and Docker Desktop runs it on Windows through WSL2, so pull and run behave the same. Two things differ from the examples above, and both are about the shell, not the image.

The mount variable is spelled differently. In PowerShell use ${PWD}; in Command Prompt use %cd%:

# PowerShell
docker run --rm -v "${PWD}:/data" ghcr.io/serradura/okf validate .
docker run --rm -v "${PWD}:/data" -p 8808:8808 ghcr.io/serradura/okf server . --bind 0.0.0.0
REM Command Prompt
docker run --rm -v "%cd%:/data" ghcr.io/serradura/okf validate .

The graph is still at http://127.0.0.1:8808 on the host, because WSL2 forwards the port.

The okf command has a PowerShell installer too, one line:

irm https://docker.okfgem.com/install.ps1 | iex

Then okf validate . and okf server . behave exactly as they do on macOS or Linux. If PowerShell says running scripts is disabled, allow local scripts once with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned. The bash install.sh also works on Windows under WSL or Git Bash.

Where next

esc
↑ ↓ navigate↵ open