Local and Docker

This page covers running the SkillsCtl server on a local machine, either from source or with Docker.

Running from source

You need Go 1.21 or later. Clone the repository if you haven’t already:

git clone https://github.com/nebari-dev/skillsctl.git
cd skillsctl

Start the server:

go run ./backend/cmd/server

Or build and run the binary:

CGO_ENABLED=0 go build -ldflags="-s -w" -o skillsctl-server ./backend/cmd/server
./skillsctl-server

Expected startup output:

2026/03/18 10:00:00 auth disabled (no OIDC_ISSUER_URL)
2026/03/18 10:00:00 starting server on :8080 (db: skillsctl.db)

The server listens on :8080 and creates skillsctl.db in the current directory.

Verify it is running:

curl localhost:8080/healthz

Expected response: ok

Dev mode

When OIDC_ISSUER_URL is not set, the server starts in dev mode:

• Authentication is disabled - all requests are accepted
• A default user identity is injected so ownership tracking works
• No credentials are needed to publish or install skills

Dev mode is useful for local development and evaluation. Do not run dev mode in production.

Configuring the port and database path

Set environment variables before starting:

PORT=9090 DB_PATH=/var/data/skillsctl.db go run ./backend/cmd/server

Or export them:

export PORT=9090
export DB_PATH=/var/data/skillsctl.db
go run ./backend/cmd/server

See Configuration reference for all available variables.

Running with Docker

Pull the image:

docker pull ghcr.io/nebari-dev/skillsctl-backend:latest

Run with a local volume for the database:

docker run -d \
  --name SkillsCtl \
  -p 8080:8080 \
  -v skillsctl-data:/data \
  -e DB_PATH=/data/skillsctl.db \
  ghcr.io/nebari-dev/skillsctl-backend:latest

The container runs as UID 65534 (non-root). Mount the volume at a path writable by that user, or pre-create the directory with appropriate permissions.

Verify:

curl localhost:8080/healthz

Running with Docker Compose

A minimal docker-compose.yml for local use:

services:
  skillsctl:
    image: ghcr.io/nebari-dev/skillsctl-backend:latest
    ports:
      - "8080:8080"
    volumes:
      - skillsctl-data:/data
    environment:
      DB_PATH: /data/skillsctl.db

volumes:
  skillsctl-data:

Start it:

docker compose up -d

Connecting the CLI

Once the server is running, configure the CLI to point at it:

skillsctl config init

Accept the default http://localhost:8080 when prompted. If the server is on a different host or port, enter that URL instead.

Next steps

• Kubernetes deployment - Helm chart for production clusters
• Configuration reference - all environment variables