https://github.com/sagikazarmark/demo-gimlet

Gimlet demo
https://github.com/sagikazarmark/demo-gimlet

Last synced: 7 months ago
JSON representation

Gimlet demo

• Host: GitHub
• URL: https://github.com/sagikazarmark/demo-gimlet
• Owner: sagikazarmark
• Created: 2023-08-29T02:36:25.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2023-08-29T02:36:35.000Z (about 2 years ago)
• Last Synced: 2025-03-06T18:52:45.162Z (7 months ago)
• Language: Nix
• Size: 10.7 KB
• Stars: 0
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# Demo: Deploying your first app with [Gimlet](https://gimlet.io/) (on a local cluster)

[![built with nix](https://builtwithnix.org/badge.svg)](https://builtwithnix.org)

In this tutorial, you can learn how to install [Gimlet](https://gimlet.io/) on a Kubernetes cluster and

deploy your first application.

Gimlet is an Open Source, GitOps based developer platform that makes deploying applications and infrastructure components

into Kubernetes easy.

You can host it yourself, but if you plan to use it in production, check out the [hosted version](https://gimlet.io/pricing).

## Prerequisites

**For an optimal experience, it is recommended to install [Nix](https://nixos.org/download.html) and [direnv](https://direnv.net/docs/installation.html).**

This tutorial comes with a [Nix](https://nixos.org)-based setup. In addition to getting all tools installed,

Nix (with the help of [devenv](https://devenv.sh/)) also keeps your global configuration files alone

(ie. your global kube config and helm repos will not be affected).

You can follow this tutorial without using Nix, but you need to install the required tools on your own:

- [Gimlet CLI](https://github.com/gimlet-io/gimlet#cli)

- [kind](https://kind.sigs.k8s.io/)

- [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl)

- [kustomize](https://kustomize.io/)

- [Helm](https://helm.sh/)

- [GitHub CLI](https://cli.github.com/)

- [Garden](https://garden.io/) _(optional)_

- [petname](https://github.com/allenap/rust-petname) _(optional)_

- [Ngrok](https://ngrok.com/)

Additional requirements:

- [Ngrok](https://ngrok.com/) account

- [GitHub](https://github.com/) account

- Internet access during the tutorial

> [!NOTE]

> Ngrok is recommended because it can easily be installed into Kubernetes as well.

> However, you can use whatever tunneling solution you want to combined with port-forwarding from the cluster.

## Preparations

Check out this repository:

```sh

git clone git@github.com:sagikazarmark/demo-gimlet.git

```

Choose a sufficiently unique, but friendly name for your demo application. You can go with something like `demo-gimlet`,

but I suggest picking a more unique name (eg. generated by [petname](https://github.com/allenap/rust-petname) or a similar tool):

```sh

echo "GIMLET_APP_NAME=gimlet-$(petname)" >> .env

```

This name will be used to create resources (eg. GitHub repository).

Configure GitHub CLI following the [documentation](https://cli.github.com/manual/#configuration).

> [!NOTE]

> **Quick tip:** Generate a new a new PAT [here]() and then paste it in a file called `.env`:

> ```sh

> echo "GITHUB_TOKEN=[TOKEN]" >> .env

> ```

Save your GitHub username for future use in `.env`:

```sh

echo "GITHUB_OWNER=$(gh api user -q ".login")" >> .env

```

Grab your Ngrok authentication details:

    - Access the [ngrok Dashboard](https://dashboard.ngrok.com/)

    - Click [Your Authtoken](https://dashboard.ngrok.com/get-started/your-authtoken). Copy the Authtoken.

    - Click [API](https://dashboard.ngrok.com/api) and follow the instructions to create a new API key. Copy the API key.

Paste the credentials in `.env`:

```sh

echo "NGROK_AUTHTOKEN=[AUTHTOKEN]" >> .env

echo "NGROK_API_KEY=[API_KEY]" >> .env

```

> [!IMPORTANT]

> `.env` is ignored in Git, so don't worry about committing it accidentally.

Next, head to the [Domains](https://dashboard.ngrok.com/cloud-edge/domains) section and create a new domain.

If you have a free account, you can claim one free static domain which is more than enough for this tutorial.

Configure your domain in the `.env` file:

```sh

echo "NGROK_DOMAIN=[DOMAIN]" >> .env

```

## Set up your Kubernetes cluster

Whether you install Gimlet on an existing cluster (running in the cloud or your machine) is up to you.

This tutorial recommends (and comes equipped for) setting up a KinD cluster. K3d is another popular option.

If you cannot run a cluster on your machine for some reasons,

consider running [vcluster](https://www.vcluster.com/) on top of an existing cluster for easier cleanup at the end.

Create a new KinD cluster:

```sh

kind create cluster

```

## Install Ngrok Ingress Controller _(optional)_

As mentioned above, using Ngrok is optional.

It's recommended because it makes exposing Gimlet to the internet easier.

Start by adding Ngrok's Helm repository:

```sh

helm repo add ngrok https://ngrok.github.io/kubernetes-ingress-controller

```

Then install the Ingress Controller:

```sh

helm install ngrok-ingress-controller ngrok/kubernetes-ingress-controller \

  --namespace ngrok-ingress-controller \

  --create-namespace \

  --set credentials.authtoken=$NGROK_AUTHTOKEN \

  --set credentials.apiKey=$NGROK_API_KEY

```

> [!NOTE]

> **Pro tip:** If you have [Garden](https://garden.io/) installed, you can run `garden deploy ngrok-ingress-controller`

Read more about installing and configuring the Ngrok Ingress Controller [here](https://ngrok.com/docs/using-ngrok-with/k8s/).

## Install Gimlet on the cluster

Set your Ngrok (or any other tunnel) domain:

```sh

cat << EOF > deploy/gimlet/ingress.patch.yaml

- op: replace

  path: /spec/rules/0/host

  value: $NGROK_DOMAIN

EOF

```

Install Gimlet:

```sh

kustomize build deploy/gimlet | kubectl apply -f -

kubectl wait deploy gimlet --for condition=Available=true --timeout=60s

```

> [!NOTE]

> **Pro tip:** If you have [Garden](https://garden.io/) installed, you can run `garden deploy gimlet`

## Configuring Gimlet

Grab the admin key from Gimlet's logs:

```sh

kubectl -n gimlet logs deploy/gimlet | grep "Admin auth key"

```

Head over to your Gimlet instance and log in with the Admin key:

```sh

open https://$NGROK_DOMAIN

```

First, let's create an API key:

- Click on your profile picture in the right upper corner of the page

- Click on **Settings**

- Enter a name for your API key (eg. demo)

- Click on **Create**

Copy the generated token and save it in `.env` (along with the server URL):

```sh

echo "GIMLET_SERVER=https://$NGROK_DOMAIN" >> .env

echo "GIMLET_TOKEN=[TOKEN]" >> .env

```

Gimlet creates a default environment for you with a unique name.

You are going to need the name of this environment before configuring the demo application.

Head over to the **Environments** section and grab the name of your environment.

(Alternatively, you can create a new one with your preferred name)

As usual, save the name in `.env`:

```sh

echo "GIMLET_ENV=[ENV]" >> .env

```

## Create demo app repository

Before moving onto configuring Gimlet, you should create a demo app repository.

This repository will hold the Gimlet manifests as well as the source code for your demo application.

The [Gimlet documentation](https://gimlet.io/docs/deploy-your-first-app) lists a number of potential demo applications,

but this tutorial uses one I prepared for this occasion: [https://github.com/sagikazarmark/template-gimlet-http-echo2](https://github.com/sagikazarmark/template-gimlet-http-echo2).

To create a new repository from this template, either click on the **Use this template** button on the repository page or run the following command:

```sh

gh repo create --public $GIMLET_APP_NAME --template sagikazarmark/template-gimlet-http-echo2

```

The above command creates a new public repository under your personal GitHub account.

In order to tell Gimlet about new versions of your application, you need to set a number of secrets and variables in your new repository:

```sh

gh secret set GIMLET_SERVER --body "$GIMLET_SERVER" --repo $GITHUB_OWNER/$GIMLET_APP_NAME

gh secret set GIMLET_TOKEN --body "$GIMLET_TOKEN" --repo $GITHUB_OWNER/$GIMLET_APP_NAME

gh variable set GIMLET_ENV --body "$GIMLET_ENV" --repo $GITHUB_OWNER/$GIMLET_APP_NAME

gh variable set GIMLET_APP --body "$GIMLET_APP_NAME" --repo $GITHUB_OWNER/$GIMLET_APP_NAME

```

Open up a new shell and check out the repository somewhere:

```sh

gh repo clone $GIMLET_APP_NAME

```

> [!NOTE]

> **Quick tip:** Print the name of the repository, then copy and run the command: `echo "gh repo clone $GIMLET_APP_NAME"`

## Configuring Gimlet

Let's continue by configuring Gimlet.

Go to the **Repositories** section and follow the instructions to set up GitHub authentication:

- Click on **Click to integrate Github on the Settings page.**

- Click on **Create Github app & Integrate Gimlet**

- Enter a name for your new GitHub app (**Pro tip:** add the unique portion of `$GIMLET_APP_NAME` to your app name)

- Click on **Create GitHub App for ...**

- Click on **Only select repositories**

- Select the repository you've created (`$GIMLET_APP_NAME`)

- Click **Install and Authorize**

After setting up the GitHub app, you should be redirected back to Gimlet and after a few seconds,

your repository should show up on the screen.

The next step is setting up our _Environment_. An Environment is basically a Kubernetes cluster where you can install your applications.

Head over to the **Environments** section and find the `gimlet environment connect` command under your environment.

Copy the command and run it. It should look something like this:

```sh

gimlet environment connect \

  --env YOUR_ENV_NAME \

  --server YOUR_SERVER_URL \

  --token SOME_TOKEN

```

Wait for a few minutes until Gimlet installs every necessary component.

## Deploying your demo application

The last step to deploy your application is telling Gimlet about it.

Create a Gimlet manifest by running the following command:

```sh

cat << EOF > gimlet.yaml

env: "$GIMLET_ENV"

app: "$GIMLET_APP_NAME"

namespace: "default"

deploy:

  branch: "*"

  event: "push"

chart:

  repository: "https://chart.onechart.dev"

  name: "onechart"

  version: "0.57.0"

values:

  gitSha: "{{ .SHA }}"

  gitRepository: "$GITHUB_OWNER/$GIMLET_APP_NAME"

  image:

    repository: "ghcr.io/$GITHUB_OWNER/$GIMLET_APP_NAME"

    tag: "{{ .BRANCH }}-{{ .SHA }}"

  containerPort: 8080

  vars:

    HELLO: Gimlet

EOF

```

Copy the manifest to the demo repository you checked out earlier:

```sh

cp gimlet.yaml path/to/repository/gimlet

```

Head over to the repository and commit the manifest:

```sh

git add .gimlet

git commit -m 'add gimlet app manifest'

git push

```

Wait for the CI to run then check your application:

```sh

kubectl get deploy

```

Open a port-forward to the application:

```sh

kubectl port-forward deploy/$GIMLET_APP_NAME 8080

```

Check that the application is running:

```sh

curl http://127.0.0.1:8080/hello

```

## Conclusion

In this tutorial, you installed Gimlet, created and deployed a demo application using Gimlet.

For more information and details, check out the [documentation](https://gimlet.io/docs/installation).

If you plan to use Gimlet in production, check out the [hosted version](https://gimlet.io/pricing).

## Cleanup

The easiest way to cleanup is deleting the cluster:

```sh

kind delete cluster

```

In the unfortunate case you need to cleanup resources from the cluster manually, you can try deleting the following namespaces:

```sh

kubectl delete namespace gimlet

kubectl delete namespace ngrok-ingress-controller

```

Make sure to delete the [GitHub application](https://github.com/settings/installations).