# Getting Started with Kuranto

The objective of this guide is to end up with a running instance of Kuranto,
able to receive and execute Forgejo Actions jobs in a Kubernetes cluster.

## Prerequisites

This guide will assume you already have:

- A running [Forgejo](https://forgejo.org/) instance
- A running [Kubernetes](https://kubernetes.io/) cluster
- The [Helm](https://helm.sh/) CLI installed

## Installing Kuranto

### Register a runner in Forgejo

The first thing we'll need to do is register a runner in our Forgejo instance.
You can do this however you like: at the instance level for a global runner,
in an organization, or in a specific repository. You can follow the official
[Forgejo Docs](https://forgejo.org/docs/latest/admin/actions/registration/) to
get a step-by-step guide on how to do this.

After registering a new runner, you will be given a configuration snippet by
Forgejo, that looks like this:

```yaml
server:
  connections:
    primary:
      url: http://your.forgejo.url.com
      uuid: A_RANDOM_UUID
      token: A_RANDOM_TOKEN
```

Copy this snippet and put it in a file named `server.yml` on your computer. Here,
we'll put it in `/tmp/server.yml`.

### Create a namespace in Kubernetes

Kuranto works by spawning pods in your Kubernetes cluster for each job it receives.
It can do this in the same namespace where Kuranto is deployed, or in a separate
dedicated namespace, if you prefer.

For the purposes of this guide, we'll have Kuranto start pods in the same namespace
it is deployed in.

Let's create that namespace:

```sh
kubectl create namespace kuranto
```

We'll use this namespace throughout the rest of this guide.

### Create the runner secret

With our namespace created, we can start populating it. The first thing we'll need is
to put the `server.yml` file we created earlier in a Kubernenetes `Secret`, so that
our Helm chart can reference it, and use it to build the final Forgejo Runner config:

```sh
kubectl -n kuranto create secret generic runner-server-config --from-file=server.yml=/tmp/server.yml
```

The Kuranto deployment managed by Helm uses an init container to merge the non-secret
config we provide to it as values, with this secret part, and create a new config
file that contains everything the Forgejo Runner needs to both work with our Forgejo
instance, as well as send jobs to Kuranto.

### Deploy Kuranto

For this deployment, we'll be using the official Helm chart provided for Kuranto, with
a very minimal configuration.

Create a `values.yaml` file somewhere with the following contents:

```yaml
kuranto:
  image:
    repository: blurrycat/kuranto
    tag: "0.3.0"
    pullPolicy: IfNotPresent

runner:
  image:
    repository: code.forgejo.org/forgejo/runner
    tag: "13.2.0"
    pullPolicy: IfNotPresent
  server:
    existingSecret: runner-server-config
  labels:
    - name: kubernetes
      image: data.forgejo.org/oci/node:lts
  config:
    log:
      level: info
      job_level: info
    runner:
      capacity: 2
```

This will deploy a Forgejo Runner with the label `kubernetes` configured, capable of
running two jobs at a time. Alongside it, the chart will also deploy Kuranto.

For labels, choose the name you want, and the image you need jobs to run on by default
when using this label. These are the same labels used in the runner configuration file
usually, but in a managed form, since we control the scheme part of the label in the
chart directly. The example label above will get formatted to `kubernetes:kubernetes://data.forgejo.org/oci/node:lts`
in the final runner configuration file.

Let's say we saved this file as `/tmp/values.yml`, we can now use it to deploy Kuranto:

```sh
helm install kuranto oci://registry-1.docker.io/blurrycat/kuranto-chart \
    --namespace kuranto
```

We should now have a deployment for the Forgejo Runner and Kuranto. We
can check this is the case by running `kubectl -n kuranto get pods`, 
which will be showing a single running pod, with two running containers 
(and a defunct init container):

- Forgejo Runner
- Kuranto

## Running jobs

Now that we have a fully working runner, we can run jobs on it! If you
already have workflows, you can simply set their `runs-on` to `kubernetes`.

If you do not have existing workflows, we can create a simple dummy one
to make sure everything is working as expected:

- Create a new repository in your Forgejo instance
- Add a `.forgejo/workflows/test.yml` file in this repository, with the
  following contents:
  ```yaml
  name: Basic
  on:
    workflow_dispatch:
  jobs:
    test:
      runs-on: kubernetes
      steps:
        - name: It works
          run: echo "it works"
  ```
- Commit this file, and push it to the repository we just created
- Go into the Actions tab, click on the `test.yml` workflow,
  and start a new run on the UI.

This should trigger a new run, that will get picked up by the runner
and sent to Kuranto. After a few seconds (depending on how long the
pull takes for the job image), you should have a successful workflow.

And, voilà! We have a fully functioning runner, executing jobs as pods
in a Kubernetes cluster!

## Going further

This guide only shows a very basic deployment of Kuranto. You can refer
to the Helm chart values to see everything you can configure on Kuranto.

To control placement of all generated job Pods, including service sidecars, use
`jobs.nodeSelector`, `jobs.affinity`, and `jobs.tolerations`. See the
[chart's scheduling examples](../charts/kuranto/README.md#job-scheduling) for simple
selectors, required or preferred node affinity, and tolerations. Kuranto reads
these settings at startup, so changing them requires a restart.

The Forgejo Runner itself can be configured through these same values.
For details on its configuration, you can refer to the sample configuration
in its [official repository](https://code.forgejo.org/forgejo/runner/src/tag/v13.1.0/internal/pkg/config/config.example.yaml).

Please note that some values in the runner configuration are managed by
the chart itself, and cannot be set through the `runner.config` value.
There are:

- `server`, this comes from the secret we made at the start of this guide
- `runner.labels`, this comes from another value in the Helm chart
- `plugins.kubernetes`, this is managed by the chart directly