Installing Gimlet on a local cluster

On this page you can learn how to install Gimlet on k3s / k3d or Rancher / Docker Desktop or Minikube or kind.

You can install Gimlet with an installer. The installer initiates a gitops environment and puts Gimlet into its gitops repository. This way Gimlet itself is managed by gitops.

You will access the dashboard with a kubectl port-forward command after installation, later you can decide to move the installation to a real domain and HTTPS.


  • A personal or organization account.
  • A Kubernetes cluster running on your laptop. Gimlet is tested with:
    • k3s / k3d
    • Rancher / Docker Desktop
    • Minikube
    • kind

Starting the installer with a oneliner

The following oneliner kickstarts the Gimlet installer.

curl -L -s | bash -s trial

Creating a Github Application

First, the installer creates a Github Application to manage all Gimlet access with it.

Creating a Github application

Install the newly created Github Application and select what repositories Gimlet should have access to. It is most convenient to allow all repositories. If you prefer a smaller set of repositories, select a few application repositories you want deploy with Gimlet and remember to extend the repository list if you want to roll out Gimlet for new apps.

Step 3 screenshot

As a final step, you also need to authorize the newly created application. Keep in mind that you are granting this access to your own Github Application. You are not granting any access to any third-party nor the Gimlet creators.

Step 4 screenshot

Bootstrapping the gitops environment

You have to provide information about the environment you are creating in this step.

You need to name the environment and set the approach to structure gitops resources. By default, Gimlet uses two gitops repositories per environment by convention, one for infrastructure components, one for application deployments.

Step 2 screenshot

Then, at the bottom of the screen, you need to select what components to install.

Component settings are prefilled with values, in general you should not change them, unless you are instructed otherwise. Some common scenarios are listed bellow.

k3s/k3d or Rancher Desktop

Enable the K3s / K3d / Rancher component.

If you use the built in Traefik ingress controller, make sure the Nginx component is turned off.

Docker Desktop

Leave everything at default.


Leave everything at default.


Leave everything at default.

Kickstarting the gitops automation

Step 2 screenshot

Once the boorstrapping is done, you have two new git repositories to store manifests in.

Follow the instructions to kickstart the automation: add deploy keys, and run kubectl commands.

Once you performed all the instructions, close the browser tab, and return to the terminal to finalize the install.

The installer script is going to check the gitops automation and if Gimlet is installed yet.

🧐 Waiting for all four gitops kustomizations become ready, ctrl+c to abort
$ kubectl get -A
NAMESPACE     NAME                                                         AGE   READY     STATUS
flux-system   gitops-repo-laszlocph-gitops-minikube-1-apps                 31s   False     dependency 'flux-system/gitops-repo-laszlocph-gitops-minikube-1-apps-dependencies' is not ready
flux-system   gitops-repo-laszlocph-gitops-minikube-1-apps-dependencies    31s   True      Applied revision: main/0195aaac0aa83c5e08c06a8b22c5f3d79ffbad06
flux-system   gitops-repo-laszlocph-gitops-minikube-1-infra                53s   Unknown   reconciliation in progress
flux-system   gitops-repo-laszlocph-gitops-minikube-1-infra-dependencies   53s   True      Applied revision: main/c7310c84029bef0dca8a3c081e5006fb736ad14b

 ✅ Gitops loop is healthy

 🧐 Waiting for Gimlet to start up in the cluster, ctrl+c to abort
$ kubectl get pods -n infrastructure | grep gimlet
NAME                                        READY   STATUS    RESTARTS      AGE
gimlet-agent-848b6f6dd5-t764c               1/1     Running   1 (31s ago)   43s
gimlet-dashboard-855b799c67-fwvjr           0/1     Running   1 (20s ago)   42s
gimletd-79dc5d546c-ksdfn                    0/1     Running   1 (15s ago)   42s
postgresql-0                                1/1     Running   0             34s

 ✅ Gimlet is up

Accessing Gimlet

You were accessing the installer on the http://gimlet.trial:9000 address. Now that the installer is stopped, you will reuse this address to access the Gimlet dashboard.

The /etc/hosts file entry already exists, you only need to forward the ingress controller to your local port 9000 to make Gimlet accessible on http://gimlet.trial:9000.


kubectl port-forward -n kube-system svc/traefik 9000:80

Rancher Desktop

kubectl port-forward -n kube-system svc/traefik 9000:80

Docker Desktop

kubectl port-forward -n infrastructure svc/ingress-nginx-controller 9000:80


kubectl port-forward -n infrastructure svc/ingress-nginx-controller 9000:80


kubectl port-forward -n infrastructure svc/ingress-nginx-controller 9000:80

Third party services to access Gimlet

Gimlet integrates to many third party tools.

To fully experience Gimlet, you have to make the Gimlet API available for third party services. On local Kubernetes clusters you can use ngrok to make that happen.

Exposing the Gimletd API for CI artifact shippers

CI artifact shippers take two parameters: Gimletd's API location and an API token. Local installations can be exposed by the following ngrok command, then you can use the ngrok URL in the GIMLET_SERVER secret in CI.

ngrok http --host-header=gimletd.trial

Exposing the Gimlet Dashboard API for Github commit webhooks

The Gimlet Dashboard uses Github webhooks to make realtime git commit information available. Without them, you have to manually refresh the Gimlet Dashboard in the browser for new commits and their statuses to show up.

The following ngrok command exposes the Gimlet Dashboard API in ngrok, and you can use the ngrok URL in the Github webhook configuration.

Please note that with a free ngrok account, you can only run a single ngrok session at a time. It is better to use the one free ngrok session for the CI shipper integration.

ngrok http --host-header=gimlet.trial

Where to go next

Congratulations, now you have a fully functioning Gimlet dashboard locally available for evaluation.

To install it on a public facing cluster, check out the other installation methods.

Installing Gimlet CLI