4. Building for Production

Once you are done with development, you may wish to make production builds. Production builds have these distinguishing properties compared to running Kui in development mode: 1) deep optimizations will be performed on the source code, thus speeding up page load time; and 2) shrink-wrapped binaries or docker images will be created.

You have two options for your production targets:

[1] Double-clickable local applications | [2] Hosted (browser-based) applications

I Want to Build Electron double-clickables

Electron is a framework for developing rich client applications, using browser technologies. Electron applications can be built to provide local double-clickable clients on Windows, macOS, and Linux.

To pack up a set of platform clients for subsequent distribution, Kui offers several npm run targets in its top-level package.json. For example, this command will build Electron clients for Windows, MacOS, and Linux:

npm run build:electron:all

When it completes, you should find (at least) three archive files in dist/electron --- one each for Windows, Linux, and MacOS. You may choose to build just for one platform by changing the "all" part to one of "win32", "mac", or "linux". You may also wish, while debugging your production builds, to skip the build step that creates the archives. To do so, set the NO_INSTALLER=true environment variable.

FAQs on Electron Client Builds

Content coming soon

• How can I customize the client, e.g. with my own custom application icon or custom application mame?
• How do I change the version displayed to users?
• How do I update or change the version of Electron used by these builds?

I Want to Build for a Hosted Application Service

You may also offer Kui in a browser-based ("hosted") deployment. There are many nuances involved in producing a viable hosted application --- those affecting security being paramount. Thus, this document does not attempt to capture a complete solution. Rather, it will give you pointers and some useful assets that can form the core of any hosted deployment of Kui.

The Architecture for a Hosted Kui

Kui can run entirely in-browser, or can have a client-server split.

Architectural Option 1: Serverless Kui

If you have no need for native helper applications (such as kubectl, which cannot run in a browser), and your static hosting service supports a sufficient security model, you may opt for the former: a "serverless" Kui. In this architecture, your application operates by serving up the Kui index.html and javascript bundles as static content. Kui includes a Read-Eval-Print loop, which can provide a Terminal experience without the need for a backing PTY.

Architectural Option 2: Proxied Kui

In most cases, you will have some need for a server-side component. To support this, Kui can run a headless form of itself in a hosted service of your choosing. The client half of Kui will then proxy a defined subset of command evaluations to that Kui proxy. It does so over a websocket connection that is established on page load (more specifically, in the current architecture, once per Kui tab).

Scripts to Aid in Building a Hosted Kui

We current have three supporting scripts:

1. Buildg production webpack bundles: npx kui-build-webpack. This command will generate the optimized webpack bundles, the index.html, and the optimized css and place them in dist/webpack. You may set the environment variable WEB_COMPRESS=true if you want to generate .js.gz bundles. You may find the webpack configuration here.

2. Build a docker image that serves up the bundles: npx kui-build-docker-with-proxy. This command will generate a docker image named kuishell/kui. This image will include an nginx server that serves the index.html and bundles (with support for serving .js.gz files); the nginx server will reverse-proxy to a Kui proxy that runs in the same container. You may find the Dockerfile here.

3. Start up this docker image: npx kui-run-cproxy. This command will start up the "containerized proxy". Visit http://localhost:9080 to try it out.

We publish prebuilt docker images to dockerhub (here). Thus, you can try out this last script without having to go through a full build (or even cloning the Kui repo) --- if your goal is only to kick the tires:

bash <(curl https://raw.githubusercontent.com/IBM/kui/master/packages/proxy/dev.sh)

That script, dev.sh is the same one invoked by npx kui-run-cproxy. It is pretty innocuous, acting only as a thin wrapper over a docker run. However, please do be careful to use it only for development; note how it injects your KUBECONFIG into the container.

Current Limitations

1. the dev.sh script which launches the container is not set up for container-to-container communication. Thus, if your API servers (e.g. kubernetes) run in other containers on the same machine, the Kui proxy will not be able to contact them. This is not an inherent limitation of Kui, rather a statement about the intentional simplicity of that script.