ui

README

Admin UI

This directory contains the client-side code for CockroachDB's web-based admin UI, which provides details about a cluster's performance and health. See the Admin UI docs for an expanded overview.

Getting Started

To start developing the UI, be sure you're able to build and run a CockroachDB node. Instructions for this are located in the top-level README. Every Cockroach node serves the UI, by default on port 8080, but you can customize the port with the --http-port flag. If you've started a node with the default options, you'll be able to access the UI at http://localhost:8080.

Our UI is compiled using a collection of tools that depends on Node.js and are managed with Yarn, a package manager that offers more deterministic package installation than NPM. NodeJS 6.x and Yarn 0.22.0 are known to work.

With Node and Yarn installed, bootstrap local development by running make in this directory. This will run yarn install to install our Node dependencies, run the tests, and compile the assets. Asset compilation happens in two steps. First, Webpack runs the TypeScript compiler and CSS preprocessor to assemble assets into the dist directory. Then, we package those assets into embedded.go using go-bindata. When you later run make build in the parent directory, embedded.go is linked into the cockroach binary so that it can serve the admin UI when you run cockroach start.

Developing

When making changes to the UI, it is desirable to see those changes with data from an existing cluster without rebuilding and relaunching the cluster for each change. This is useful for rapidly visualizing local development changes against a consistent and realistic dataset.

We've created a simple NodeJS proxy to accomplish this. This server serves all requests for web resources (JavaScript, HTML, CSS) out of the code in this directory, while proxying all API requests to the specified CockroachDB node.

To use this proxy, run ./proxy.js <target-cluster-http-uri> and navigate to http://localhost:3000 to access the UI.

When you're ready to submit your changes, be sure to run make in this directory to regenerate the on-disk assets so that your commit includes the updated embedded.go. This is enforced by our build system, but forgetting to do this will result in wasted time waiting for CI. We commit this generated file so that CockroachDB can be compiled with minimal non-go dependencies.

If you get cryptic TypeScript compile/lint failures upon running make that seem completely unrelated to your changes, try removing yarn.installed and node_modules before re-running make (do NOT run yarn install directly).

Be sure to also commit modifications resulting from dependency changes, like updates to package.json and yarn.lock.

Running tests

If you'd like to run the tests directly you can run make test. If you're having trouble debugging tests, we recommend using make test-debug which prettifies the test output and runs the tests in Chrome. When a webpage opens, you can press the debug button in the top right-hand corner to run tests and set breakpoints directly in the browser.

Documentation

Overview

Package ui embeds into the Cockroach certain data such as web html and stylesheets.

Index

• func Asset(name string) ([]byte, error)
• func AssetDir(name string) ([]string, error)
• func AssetInfo(name string) (os.FileInfo, error)
• func AssetNames() []string
• func MustAsset(name string) []byte
• func RestoreAsset(dir, name string) error
• func RestoreAssets(dir, name string) error

Functions

func Asset

func Asset(name string) ([]byte, error)

Asset loads and returns the asset for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetDir

func AssetDir(name string) ([]string, error)

AssetDir returns the file names below a certain directory embedded in the file by go-bindata. For example if you run go-bindata on data/... and data contains the following hierarchy:

data/
  foo.txt
  img/
    a.png
    b.png

then AssetDir("data") would return []string{"foo.txt", "img"} AssetDir("data/img") would return []string{"a.png", "b.png"} AssetDir("foo.txt") and AssetDir("notexist") would return an error AssetDir("") will return []string{"data"}.

func AssetInfo

func AssetInfo(name string) (os.FileInfo, error)

AssetInfo loads and returns the asset info for the given name. It returns an error if the asset could not be found or could not be loaded.

func AssetNames

func AssetNames() []string

AssetNames returns the names of the assets.

func MustAsset

func MustAsset(name string) []byte

MustAsset is like Asset but panics when Asset would return an error. It simplifies safe initialization of global variables.

func RestoreAsset

func RestoreAsset(dir, name string) error

RestoreAsset restores an asset under the given directory

func RestoreAssets

func RestoreAssets(dir, name string) error

RestoreAssets restores an asset under the given directory recursively