Reference
Gimlet Dashboard configuration reference
On this page you are going to install Gimlet Dashboard and connect it to Github and GimletD.
The preferred method to install Gimlet Dashboard is through the Gimlet Installer. This page is a full configuration reference should you need to adjust the configuration.
Installation yamls and configuration
You can get the Kubernetes yamls by rendering the Helm chart with the minimum configuration you can see bellow:
cat << EOF > values.yaml
image:
repository: ghcr.io/gimlet-io/gimlet-dashboard
tag: latest
pullPolicy: Always
containerPort: 9000
probe:
enabled: true
path: /
EOF
helm repo add onechart https://chart.onechart.dev
helm template gimlet-dashboard onechart/onechart -f values.yaml
Expose the Gimlet Dashboard with an Ingress
image:
repository: ghcr.io/gimlet-io/gimletd
tag: latest
probe:
enabled: true
path: /
[...]
+ingress:
+ annotations:
+ kubernetes.io/ingress.class: nginx
+ cert-manager.io/cluster-issuer: letsencrypt
+ host: gimlet.mycompany.com
+ tlsEnabled: true
Add basic Dash config
image:
repository: ghcr.io/gimlet-io/gimlet-dashboard
tag: latest
pullPolicy: Always
containerPort: 9000
probe:
enabled: true
path: /
+vars:
+ HOST: gimlet.mycompany.com
+ JWT_SECRET: <<$(openssl rand -hex 32)>>
HOST
Gimlet Dash must know what address it is running on. It uses this hostname to register webhooks on Github.JWT_SECRET
is the secret to generate agent JWT tokens
Integrate it with GimletD
To be able to deploy / rollback and to look at the deploy history, you must connect your Gimlet Dash to GimletD, the release manager.
image:
repository: ghcr.io/gimlet-io/gimlet-dashboard
tag: latest
pullPolicy: Always
containerPort: 9000
probe:
enabled: true
path: /
[...]
+vars:
+ GIMLETD_URL: gimletd.mycompany.com
+ GIMLETD_TOKEN: <<a GilmetD admin token>>
Integrate it with Github
Gimlet Dashboard uses a Github Application to gain access to your source code.
You must create this application first.
Granting access
Please note that this application is created by you, and you don't give access to your source code to any third party or the makers of Gimlet.
Creating a Github Application
Let's create first the Github Application.
The application requires various permissions, and you have to perform further actions like you generating a private key and so on. Instead of a lengthy guide, we prepared a script for you that does all that on Github.
The following snippet, writes a html file on your disk and opens it in your browser, where you find a "Create Github app" button.
When you click the "Create Github app" button, you are forwarded to Github where you can confirm your application's name. All settings are sent to Github in a json structure, holding the required permission list, webhook URLs and so on, so you don't have to perform too many manual steps.
Now scan the source of the HTML file, and replace gimlet.mycompany.com
with the URL you are going to host Gimlet Dash on.
cat << EOF > create-app.html
<form action="https://github.com/settings/apps/new" method="post">
<input type="hidden" name="manifest" id="manifest"><br>
<input type="submit" value="Create Github app">
</form>
<script>
var url = new URL(window.location);
var code = url.searchParams.get("code");
if (code) {
var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
if (xhr.readyState === 4) {
console.log(xhr.response)
var responseObj = JSON.parse(xhr.response)
document.open();
document.write('<p>GITHUB_APP_ID: ' + responseObj.id + '</p>');
document.write('<p>GITHUB_CLIENT_ID: ' + responseObj.client_id + '</p>');
document.write('<p>GITHUB_CLIENT_SECRET: ' + responseObj.client_secret + '</p>');
document.write('<p>GITHUB_PRIVATE_KEY: <br/>' + responseObj.pem.replaceAll('\n', '<br/>') + '</p>');
document.close();
}
}
xhr.open("POST", "https://api.github.com/app-manifests/"+code+"/conversions", true);
xhr.send();
}
</script>
<script>
input = document.getElementById("manifest")
input.value = JSON.stringify({
"name": "Gimlet Dash",
"url": "https://gimlet.mycompany.com",
"callback_url": "https://gimlet.mycompany.com/auth",
"hook_attributes": {
"url": "https://gimlet.mycompany.com/hook"
},
"redirect_url": "http://127.0.0.1:11111/create-app.html",
"public": false,
"default_permissions": {
"checks": "read",
"contents": "write",
"repository_hooks": "write",
"statuses": "read",
"members": "read"
},
"default_events": [
"create",
"push",
"delete",
"status",
"check_run"
]
})
</script>
EOF
PORT=11111 npx http-server -o /create-app.html
Once you clicked the "Create Github app" button, and confirmed the app's name on Github, you are redirected to a page that shows all the required configuration values for Gimlet Dashboard.
Copy them to your Helm values file accordingly.
image:
repository: ghcr.io/gimlet-io/gimlet-dashboard
tag: latest
pullPolicy: Always
containerPort: 9000
probe:
enabled: true
path: /
+vars:
+ GITHUB_APP_ID: 123456789
+ GITHUB_INSTALLATION_ID: "987654321"
+ GITHUB_PRIVATE_KEY: |
+ -----BEGIN RSA PRIVATE KEY-----
+ MIIEowIBAAKCAQEAxpLdgC6KEDFPx5...
+ ...
+ GITHUB_CLIENT_ID: Iv1.123456
+ GITHUB_CLIENT_SECRET: xxx
One last step is to provide the GITHUB_ORG
variable. Users that are members of this Github Organization will be able to authenticate to the dashboard.
image:
repository: ghcr.io/gimlet-io/gimlet-dashboard
tag: latest
pullPolicy: Always
containerPort: 9000
probe:
enabled: true
path: /
vars:
+ GITHUB_ORG: mycompany
GITHUB_APP_ID: 123456789
GITHUB_INSTALLATION_ID: 987654321
GITHUB_PRIVATE_KEY: |
-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEAxpLdgC6KEDFPx5...
...
GITHUB_CLIENT_ID: Iv1.123456
GITHUB_CLIENT_SECRET: xxx
To obtain the INSTALLATION_ID
, navigate to https://github.com/settings/apps and edit your just created application. Click Install App in the sidebar to install it on the account that you want GimletD to access.
You can copy the INSTALLATION_ID
from your browsers address bar after installation. The URL will be in the following format: https://github.com/settings/installations/$INSTALLATION_ID
That's all.
Now you integrated Gimlet Dash with Github.
If you are in doubt about the process, you can crosscheck our script with Github's general guide on how to create a Github Application here
You can also validate our script on Github's Creating a GitHub App from a manifest guide
Persistence
Volumes to back the state
image:
repository: ghcr.io/gimlet-io/gimlet-dashboard
tag: latest
pullPolicy: Always
containerPort: 9000
probe:
enabled: true
path: /
+volumes:
+ - name: data
+ path: /var/lib/gimlet-dashboard
+ size: 1Gi
+ storageClass: default
+ - name: repo-cache
+ path: /tmp/gimlet-dashboard
+ size: 5Gi
+ storageClass: default
data
volume to back the SQLite database where Gimlet Dashboard keeps its datarepo-cache
is where Gimlet Dashboard checks out git repositories of your applications. Data can be cleaned from this disk, it serves only as cache.
Using Postgresql
If you prefer, you can use Postgresql instead of SQLite.
image:
repository: ghcr.io/gimlet-io/gimlet-dashboard
tag: latest
pullPolicy: Always
containerPort: 9000
probe:
enabled: true
path: /
volumes:
- - name: data
- path: /var/lib/gimlet-dashboard
- size: 1Gi
- storageClass: default
- name: repo-cache
path: /tmp/gimlet-dashboard
size: 5Gi
storageClass: default
+vars:
+ DATABASE_DRIVER: postgres
+ DATABASE_CONFIG: "postgres://gimlet_dashboard:yourpassword@postgresql:5432/gimlet_dashboard?sslmode=disable"
Connect the Gimlet Agent
To finish the setup continue with the Installing the Gimlet Agent guide