Running cljdoc locally

Table of Contents

Introduction
Run cljdoc Locally From Source (cljdoc developer)
- Prerequisites
- Setup cljdoc
Run cljdoc Locally From Docker (library author)
- Prerequisites
- Setup cljdoc docker
Import a Library’s Docs
Offline Bundles
Example Docker Scripts

Introduction

There are different motivations for running cljdoc locally on your computer:

You are a cljdoc developer wanting to contribute to cljdoc itself. You will want to run cljdoc locally from source.
You are a library author interested in verifying that your docs look good before publishing. You can opt to:
- run cljdoc locally from docker to avoid any local source setup
- or run cljdoc locally from source

Regardless of the path you take, after you start cljdoc locally, you’ll need to import a library’s docs so you have something to test against.

Run cljdoc Locally From Source (cljdoc developer)

This is the path to take for a cljdoc developer.
While it is also a viable path for a library author, a library author might prefer to run cljdoc locally from docker.

Prerequisites

To run cljdoc from source, you must first install these dependencies:

Node.js

Java Development Kit 17 - the cljdoc web server currently runs on JDK17 in production, so ideally, you’ll want to be developing with JDK17 too. Example of a valid JDK:

$ java -version
openjdk version "17.0.1" 2021-10-19
OpenJDK Runtime Environment Temurin-17.0.1+12 (build 17.0.1+12)
OpenJDK 64-Bit Server VM Temurin-17.0.1+12 (build 17.0.1+12, mixed mode, sharing)

Clojure CLI tools - make sure you have upgraded to the current version
Babashka - some of our scripts are written in babashka
Git

Setup cljdoc

Clone cljdoc (adjust as appropriate when you are working from a fork of cljdoc)
```
git clone https://github.com/cljdoc/cljdoc.git
cd cljdoc
```

Build the JavaScript files used by the cljdoc pages:

If you want to replicate production:

npm ci                 # reproducibly install packages into node_modules
npm run format         # format JS code with Prettier
npm run build          # production build

Check that resources-compiled folder was generated.

If you are a developer planning to work on JavaScript files (instead of npm run build we have npm run dev):

npm ci                 # reproducibly install packages into node_modules
npm run format         # format JS code with Prettier
npm run dev            # watch mode for automatic rebuilding of JavaScript files

Note	Leave watch mode session open. Continue any work in a separate terminal shell.

Start the cljdoc web server
```
./script/cljdoc run
```
Note
Leave this web server session open. Continue any work in a separate terminal shell.

Alternatively you can start a REPL with clj (or your favorite editor integration), then load the system, move into its namespace and start the server:
```
(require '[cljdoc.server.system])
(in-ns 'cljdoc.server.system)
(require '[integrant.repl])
(integrant.repl/set-prep! #(system-config (cfg/config)))
(integrant.repl/go)
```
(Optional, but recommended) Run tests. It is recommended that you run tests before making any changes. This way you’ll be pretty sure that the cljdoc main branch and your local setup are sound. From the cljdoc directory:
```
clojure -M:test
```

Run cljdoc Locally From Docker (library author)

If you are a library author, this path is for you; cljdoc developers need to run cljdoc locally from source.

Here we make use of the very same cljdoc docker image that runs in production and avoid any local cljdoc source setup.

Prerequisites

You’ll need docker.

Setup cljdoc docker

Tip	Your installation might require you to prefix docker commands with `sudo`, add your user to the docker group or adapt as necessary.

Fetch any updates for the docker image so that we match what is running in production:
```
docker pull cljdoc/cljdoc
```
Make a directory for the cljdoc sqlite database:
```
mkdir -p /tmp/cljdoc
```

Start the cljdoc docker web server:

docker run --rm \
  --publish 8000:8000 \
  --volume "$HOME/.m2:/root/.m2" \
  --volume /tmp/cljdoc:/app/data \
  cljdoc/cljdoc

Note	Leave this terminal open. Open a separate terminal shell for any other work.

Import a Library’s Docs

Before importing a library for local testing, you will have decided if you want to run cljdoc locally from source or run cljdoc locally from docker. See the Introduction section on how to make that choice.

Here’s an overview of importing library docs when running cljdoc locally:

Note:

A cljdoc developer won’t necessarily want to work with a local library; they can skip to step 3 and import a published library.
In the discussions that follow, we’ll assume that your hosted SCM (Source Code Management) system is GitHub.

Important

If your project has sub modules, you’ll need to ingest each of the sub modules in order to see their APIs on your locally running cljdoc web server.

Example Library

We have chosen cljdoc-exerciser, a project the cljdoc team uses to review cljdoc rendering and formatting features, as our example import library. Feel free to substitute your own, or another, library when walking through examples.

The ingest Command

The cljdoc command line tool includes an ingest command. You will use this command to import a library’s documentation into cljdoc when working locally.

All example commands assume you are running from your library project root dir, and that if you are running from cljdoc source, both projects share the same parent dir.

The sections that follow include example commands for running from cljdoc source and docker. For example to get help on the ingest command:

from source	from docker
../cljdoc/script/cljdoc ingest --help	docker run --rm \ --entrypoint clojure cljdoc/cljdoc \ -M:cli ingest --help

Tip	Your installation might require you to prefix docker commands with `sudo`, adapt as necessary.

Steps

Tip	Repeat steps 1 through 4 as needed (see overview diagram). Confusion can usually be resolved by asking: Did I remember to commit/push? Did I remember to publish locally?

Setup)

If you just want to import an existing libary, jump to import a published library.

If you are going to walk through the examples, you’ll want to clone cljdoc-exerciser. Fork it if you want to walk though pushing changes for a full preview.

Step 1) Commit/Push Library Changes

Cljdoc only imports from committed changes, this means you’ll need to commit any changes before import.

If you want a full preview where relative GitHub references (links to images, source code, etc) work, then you’ll also want to push your commits to GitHub.

Step 2) Publish Library Locally

After setup, to publish cljdoc-exerciser to your local maven repository, run:

bb install

The command issued to install a library to the local maven repo varies by build technology (leiningen, boot, tools deps cli, etc) and project. The bb install command is appropriate for cljdoc-exerciser, be sure to use the appropriate command for your project.

Step 3) Import Library Docs

We go over a few different import scenarios:

Import a Published Library

You want to import library docs for a publicly published library. This is a likely scenario for a cljdoc developer.

Tip	If you have been testing cljdoc-exerciser 1.0.77 locally, be sure to first delete it from your local maven repository.

To import cljdoc-exerciser 1.0.77:

from source

from docker

../cljdoc/script/cljdoc ingest \
  --project org.cljdoc/cljdoc-exerciser \
  --version 1.0.77

docker run --rm \
  --volume "$HOME/.m2:/root/.m2" \
  --volume /tmp/cljdoc:/app/data \
  --entrypoint clojure \
  cljdoc/cljdoc -M:cli ingest \
    --project org.cljdoc/cljdoc-exerciser \
    --version 1.0.77

Testing docs for a Library During Development

You are in development mode on a library and want to preview what its docs will look like on cljdoc.

Normally cljdoc will look in your published library’s pom.xml under project/scm to learn what GitHub url and tag it should use to reference articles and source code. To avoid having to alter your pom.xml while testing changes during development, the cljdoc ingest command provides:

--git to override pom.xml project/scm/url
--rev to override pom.xml project/scm/tag

You have a choice on how to handle relative references from docs to other files (e.g. images, source code, etc) in your library’s GitHub repository when testing locally:

Quick preview --git specifies your library’s root directory on your local filesystem.

Warning

In a quick preview, relative references to GitHub WON’T work.

From cljdoc-exerciser’s root dir:

from source

from docker

../cljdoc/script/cljdoc ingest \
  --project org.cljdoc/cljdoc-exerciser \
  --version 1.0.77 \
  --git $(pwd) \
  --rev $(git rev-parse HEAD)

docker run --rm \
  --volume $(pwd):/repo-to-import \
  --volume "$HOME/.m2:/root/.m2" \
  --volume /tmp/cljdoc:/app/data \
  --entrypoint clojure \
  cljdoc/cljdoc -M:cli ingest \
    --project org.cljdoc/cljdoc-exerciser \
    --version 1.0.77 \
    --git /repo-to-import \
    --rev $(git rev-parse HEAD)

Full preview --git specifies your library’s https GitHub project URL.

Note	In a full preview, relative references to GitHub DO work.

Tip	Change `https://github.com/cljdoc/cljdoc-exerciser` if you have forked cljdoc-exerciser.

From cljdoc-exerciser’s root dir:

from source

from docker

../cljdoc/script/cljdoc ingest \
  --project org.cljdoc/cljdoc-exerciser \
  --version 1.0.77 \
  --git https://github.com/cljdoc/cljdoc-exerciser \
  --rev $(git rev-parse HEAD)

docker run --rm \
  --volume "$HOME/.m2:/root/.m2" \
  --volume /tmp/cljdoc:/app/data \
  --entrypoint clojure \
  cljdoc/cljdoc -M:cli ingest \
    --project org.cljdoc/cljdoc-exerciser \
    --version 1.0.77 \
    --git https://github.com/cljdoc/cljdoc-exerciser \
    --rev $(git rev-parse HEAD)

Verifying docs Prior to Publish to Clojars

You are getting ready to release to clojars and want to check for possible configuration errors and verify what your docs will look like on cljdoc.

Tip	If you have fully automate your deployment, including updating/generating your `pom.xml`, this verification will not apply.

When a project is published to clojars its docs are automatically updated on cljdoc. A not entirely uncommon occurrence is a malconfigured project/scm in pom.xml and therefore wrong or missing references to GitHub.

To test your scm settings before release to clojars:

Commit and push all your changes to GitHub
Update your pom.xml project/version and project/scm appropriately.
- Do this manually or via whatever tooling you use to do that, for cljdoc-exerciser run script/update-pom.
- Update pom.xml project/scm/url if you are working from a fork.
Publish your library to your local maven repo
- For cljdoc-exerciser run bb install.

Then test your via a cljdoc ingest that omits --git and --rev. This way, cljdoc will use the values in your pom.xml.

From cljdoc-exerciser’s root dir:

from source

from docker

../cljdoc/script/cljdoc ingest \
  --project org.cljdoc/cljdoc-exerciser \
  --version 1.0.77

docker run --rm \
  --volume "$HOME/.m2:/root/.m2" \
  --volume /tmp/cljdoc:/app/data \
  --entrypoint clojure \
  cljdoc/cljdoc -M:cli ingest \
    --project org.cljdoc/cljdoc-exerciser \
    --version 1.0.77

Step 4) Browse Library Docs

The final step is you browsing the imported library docs in your web browser. For example, after importing version 1.0.77 of cljdoc-exerciser you’d browse the docs locally via:
http://localhost:8000/d/org.cljdoc/cljdoc-exerciser/1.0.77

Offline Bundles

When testing locally, you may also want verify what a library docs look like as an offline bundle.

The cljdoc command line tools includes an offline-bundle command, but it is probably easier to just use your local running cljdoc web server to generate the offline bundle.

You’ll want to first start a cljdoc server, then import a library’s docs.

Assuming cljdoc-exerciser version 1.0.77 navigate to:
http://localhost:8000/download/org.cljdoc/cljdoc-exerciser/1.0.77.

Example Docker Scripts

The above examples show the minimal commands to run cljdoc under docker and almost beg for scripting. Here are some example scripts from the wild:

clj-kondo
rewrite-cljc

Thats pretty much it! Stop by on Slack if you have any problems!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

running-cljdoc-locally.adoc

running-cljdoc-locally.adoc

Running cljdoc locally

Introduction

Run cljdoc Locally From Source (cljdoc developer)

Prerequisites

Setup cljdoc

Run cljdoc Locally From Docker (library author)

Prerequisites

Setup cljdoc docker

Import a Library’s Docs

Example Library

The ingest Command

Steps

Setup)

Step 1) Commit/Push Library Changes

Step 2) Publish Library Locally

Step 3) Import Library Docs

Import a Published Library

Testing docs for a Library During Development

Verifying docs Prior to Publish to Clojars

Step 4) Browse Library Docs

Offline Bundles

Example Docker Scripts

Files

running-cljdoc-locally.adoc

Latest commit

History

running-cljdoc-locally.adoc

File metadata and controls

Running cljdoc locally

Introduction

Run cljdoc Locally From Source (cljdoc developer)

Prerequisites

Setup cljdoc

Run cljdoc Locally From Docker (library author)

Prerequisites

Setup cljdoc docker

Import a Library’s Docs

Example Library

The ingest Command

Steps

Setup)

Step 1) Commit/Push Library Changes

Step 2) Publish Library Locally

Step 3) Import Library Docs

Import a Published Library

Testing docs for a Library During Development

Verifying docs Prior to Publish to Clojars

Step 4) Browse Library Docs

Offline Bundles

Example Docker Scripts