Installation

This page gets Veckl running on your workstation. For cluster installation, use this page for configuration first, then continue to Kubernetes or Zarf Air Gap.

Requirements

Install these tools before you start:

• Go 1.22 or newer.
• Node.js 22 or newer.
• npm.
• Git.
• Access to a GitHub or GitHub Enterprise Server repository where Veckl will store test cases.

For container or cluster deployments, also install:

• Podman or a Docker-compatible image builder.
• Kubernetes CLI access for the target cluster.
• Zarf if you are preparing a disconnected deployment.

Get the Source

Clone the repository and enter the project directory:

git clone https://github.com/hinsonct/veckl.git
cd veckl

Create Local Configuration

Copy the template:

cp .env.template .env

Fill in the GitHub App, OAuth, repository, and session values in .env. The required fields are explained in Configuration.

Generate secure session keys:

./scripts/generate-session-keys.sh

Then verify the file:

./scripts/verify-env.sh .env

Tip

The session keys must be standard base64 strings that decode to 32 bytes. The generator script creates values in the right format.

Install Frontend Dependencies

The make dev command installs frontend dependencies automatically if frontend/node_modules is missing. If you want to install them yourself:

cd frontend
npm install
cd ..

Start Veckl

Start the backend and frontend together:

make dev

Open:

http://localhost:3000

make dev starts:

• Go backend on http://localhost:8080 unless PORT is set.
• Next.js frontend on http://localhost:3000.

Stop both processes with Ctrl+C, or run:

make dev-stop

Useful Commands

make build
make run
make test
make lint
make clean

Frontend-only commands:

cd frontend
npm run dev
npm run typecheck
npm run lint
npm test

Next Step

If login is not configured yet, continue to GitHub Setup. If GitHub is ready, continue to First Run.