ui

README

Embedded UI

This directory contains the client-side code for cockroach's web admin console. These files are embedded into the cockroach binary via the go-bindata package, which is used to generate the embedded.go file in this directory.

Getting Started

To get started with the UI, be sure you're able to build and run the CockroachDB server. Instructions for this are located in the top-level README.

To bootstrap local development, you'll need to run make in this directory; this will download the dependencies, run the tests, and build the web console assets.

Next, confirm that you can load the UI in debug mode by running the server with the environment variable COCKROACH_DEBUG_UI set to a truthy value, e.g. COCKROACH_DEBUG_UI=1 (though any value accepted by strconv.ParseBool will work) and navigating to the web console.

Visual Studio Code

To get autocomplete and type-checking working in Visual Studio Code, you may need to manually configure your typescript version. Typescript 2 is already installed by npm, but you'll need to configure your project/workspace to point to it. See https://code.visualstudio.com/docs/languages/typescript#_using-newer-typescript-versions.

Modification

As mentioned above, be sure to run the CockroachDB server in UI debug mode while developing the web console. This causes the CockroachDB server to serve assets directly from the disk, rather than use the compiled-in assets. These assets will be compiled in the browser each time the page is reloaded.

NOTE: styles are not yet compiled in the browser. As a workaround, make watch is available; it automatically watches for style changes and recompiles them, though a browser reload is still required. Note that if you add a new file, you'll need to restart make watch.

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 the build.

We commit the generated file so that CockroachDB can be compiled with minimal non-go dependencies.

Live Reload

The UI also supports live reload in debug mode. To take advantage of this, run make livereload from this directory - the UI will automatically reload files as you modify them, taking advantage of TypeScript's incremental compilation.

Dependencies

Our web console is compiled using a collection of tools that depends on Node.js, so you'll want to have that installed.

We use npm to manage various dependencies; be sure that your Node.js installation includes a recent version of npm. If you observe problems with npm, try updating it using npm install -g npm.

To modify an existing npm dependency, you'll need to edit package.json in the standard fashion, while to add a new npm dependency, you'll want to run npm install --save <myAwesomeDep>.

Either way, complete any npm changes by running:

rm -rf node_modules npm-shrinkwrap.json && npm update --no-progress && $(npm bin)/shonkwrap && $(npm bin)/jspm update

We use JSPM to manage frontend dependencies and Typings to manage typescript definition files. Our Makefile automatically installs these tools locally, so for the most part, you can be blissfully ignorant of their use. However, if you wish to add JSPM/Typings dependencies (and do not have your own opinions on binstubs), you'll want to run them from the local install using one of:

• $(npm bin)/jspm install --save <myAwesomeDep>
• $(npm bin)/typings install --save <myAwesomeDep>

Be sure to commit any changes resulting from your dependency changes.

The --save modifiers and shonkwrap invocation above are necessary to properly lock down dependencies for other developers on the project, so make sure you don't elide them!

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