Quick local installation option for developer sneak peak

[laszlocph]

Feedback is that trying Gimlet locally has a high bar of entry.

The Gimlet installer today requires a real domain name, a Kubernetes cluster that can create a Service resource with a public IP where Let's Encrypt can verify domain ownership. This rules out any local Kubernetes option. The goal of this issue is to provide an installer option that works locally in Docker/Rancher Desktop, k3s, k3d, Minikube or kind.

[laszlocph]

The main hurdle with Gimlet installer today is to create a Github Application

• that provides access tokens for API communication
• and handles OAuth authentication.

The OAuth flow has a built in security feature that validates the source URL where the authentication was initiated from. This security feature mandates the installer to run on the same domain, and same HTTP protocol schema (https!). This is the reason that the installer needs sudo (to run on port 443) and a host file entry (to run on the same domain name as where it will be installed to).

If we could use a Github Personal Access Token (PAT) for the local installation, and postpone or skip application creation, we could spare the need for a domain name, and the need for HTTPS.

Host file entries do not work well with local Kubernetes options either.

[laszlocph]

Considerations:

• with a PAT, should we allow repo creation under personal git account, or also under Github Organization?
  • UPDATE: both works
• Agent - Dashboard and Dashboard - Gimletd communication should happen on cluster network, no need for host names
• Dashboard should be accessible with kubectl port-forward
• Dashboard authentication should happen via OAuth or a special case local auth?
  • potentially we can use the PAT to create a Github Application and configure OAuth to a host file controlled domain name. OAuth happens on the laptop's browser, so the local K8s solution's limitation doesn't matter here
  • we can also use the PAT to later on "eject" the local install, and make it permanent by updating the Github Application to point to the final URL [UPDATE]: Github Apps cannot be updated via the API. So this has to be a manual process
  • potentially this method could be the canonical way for production install too. The PAT could be a way to bootstrap first without domain and https, then move to a real infrastructure
• would Github webhooks work locally? No, perhaps with an ngrok/inlets tunnel.
• would the shipper API calls work locally? No, perhaps with an ngrok/inlets tunnel.
• we should make the install of cert manager, and nginx ingress optional, but ingress architecture mandatory, bring your own ingress

[laszlocph]

We set out with three goals in mind:

• not needing to use an unsafe https page in the installer
• no need for sudo in the installer
• agent - dashboard and dashboard - gimletd communication should happen on cluster network

PAT seemed to be a solution to delay application creation and configuration. Turned out Github has no API for modifying Github Applications. Understandably, this is the place where the user grants access 3rd parties. Must validate by a human.

not needing to use an unsafe https page in the installer

:green_apple: This is resolved by not mandating https during the installation process. This will be later enabled where the user needs to manually change the Github Application URLs to https

no need for sudo in the installer

:orange_circle: This remains as a requirement. OAuth is sensitive to ports, and we must do an OAuth in the installer to get an access token. We don't want to do a PAT based installer, as it is not able to solve the Github Appplication configuration problem, thus just convolutes the picture and doesn't solve anything. We can't use PAT for Gimlet, that would require too many changes.

• agent - dashboard and dashboard - gimletd communication should happen on cluster network

:green_apple: Solved. The installer installs the agent, the dashboard and gimletd on the same cluster. Settings were created to make use of this assumption.

would the shipper API calls work locally? No, perhaps with an ngrok/inlets tunnel.

ngrok http --host-header=gimletd.laszlo.local 172.28.0.2:80 will expose the API to CI engines.

would Github webhooks work locally? No, perhaps with an ngrok/inlets tunnel.

we can only run a single ngrok. With a single host header. So either gimlet dashboard or gimletd works. We chose gimletd for shippers to work

[laszlocph]

Done if:

• [x] Local installer on k3s, k3d
• [x] Rancher Desktop tested
• [x] Local installer on Docker Desktop tested
• [x] Local install documented
• [x] Captioned installer video removed
• [x] Documented how to move to HTTPS
• [x] Production install on other generic cloud provider tested

[laszlocph]

no need for sudo in the installer

🍏 Since Rancher Desktop runs k3s in a VM, I needed to port-forward the ingress controller port to my laptop on a port that is not 80. If I add this port forward step on the local k3d installation step as well, port 80, thus sudo is not a requirement. Sudo will be removed from the installer flow.

Rancher Desktop, k3s, k3d: kubectl port-forward -n kube-system svc/traefik 9000:80
Docker Desktop: kubectl port-forward -n infrastructure svc/ingress-nginx-controller 9000:80

This means that the platform engineer must manually change the port once she moved to a real installation. But she needed to due this because of SSL already. So removing sudo does not add anything major to the installer flow.

[laszlocph]

https://github.com/gimlet-io/gimlet-documentation/pull/4