Skip to content

Getting Started

Prerequisites

  • Docker installed and running
  • Task installed (brew install go-task)

Installation

git clone git@git.clarity-innovations.com:internal/claritools.git
cd claritools

Setup

Run the interactive setup wizard:

task init

You will be prompted to choose an environment:

Select environment:
  1) local  - Local development with self-signed certs
  2) dev    - Local + OIDC auth (Keycloak + oauth2-proxy)
  3) cd     - Multi-dev server with Let's Encrypt

Choice [1/2/3]:

This creates a .env file and registers claritools in your global ~/Taskfile.yml so you can run tasks from any directory.

Which mode should I choose?

  • Choose local if you are developing Docker-based applications and want a clean HTTPS proxy with a dashboard.
  • Choose dev if you are working on claritools itself and need to test OIDC authentication.
  • Choose cd only on the production multi-dev server (nirn.clarity-innovations.com).

Generate certificates (local and dev only)

Local and dev modes use self-signed certificates for *.local.ciservers.net. Generate them once:

task generate-local-self-signed-certs

This creates certs/self.crt and certs/self.key (RSA-4096, valid for 365 days). No local OpenSSL install is required — it runs inside a temporary Docker container.

Note

Your browser will show a certificate warning on first visit. Accept the self-signed certificate to proceed.

Start the stack

task start

This starts the appropriate services for your configured environment. Visit the dashboard:

Mode Dashboard URL
local / dev https://dashboard.local.ciservers.net
cd https://dashboard.cd.ciservers.net

Verify the setup

task doctor

This runs health checks for your environment and reports any issues with suggested fixes.

Switching environments

To switch between environments, run task init again and select a different option. Then restart:

task init
task restart