bobtfish/uchiwa repository overview

⁠Uchiwa

Uchiwa is a simple dashboard for the Sensu monitoring framework, built with Node.js and AngularJS.

The dashboard is under active development, and major changes are not uncommon.

⁠Features

• Support of multiple Sensu APIs
• Real-time updates with Socket.IO
• Client and checks stashes management
• Easily filter events, clients, stashes and events
• Simple client details view
• Easy installation

⁠Screenshots

⁠Getting Started

⁠From source

• Checkout the source: git clone https://github.com/sensu/uchiwa.git
• Install bower on your system: npm install -g bower
• Install the dependencies:
  • With root user: npm install --production --unsafe-perm
  • With normal user: npm install --production
• Copy config.json.example to config.json - modify your Sensu API information. See configuration section below
• Start the dashboard: node app.js
• Open your browser: http://localhost:3000/

⁠With packages

See Sensu documentation⁠

⁠Configuration

⁠sensu

• host - String: The address of the Sensu API.
• ssl - Boolean: Determines whether or not the API use a SSL certificate.
• port - Integer: The port of the Sensu API. The default value is 4567.
• user - String: The username of the Sensu API. Leave empty for none.
• pass - String: The password of the Sensu API. Leave empty for none.
• path - String: The path of the Sensu API. Leave empty in case of doubt.
• timeout - Integer: Timeout for the Sensu API, in milliseconds. The default value is 5000.

⁠uchiwa

• user - String: The username of the Uchiwa dashboard. Leave empty for none.
• pass - String: The password of the Uchiwa dashboard. Leave empty for none.
• stats - Integer: Determines the retention, in minutes, of graphics data. The default value is 10.
• refresh - Integer: Determines the interval to pull the Sensu API, in milliseconds. The default value is 10000.

⁠Docker

This application comes pre-packaged in a docker container for easy deployment.

There are two ways of running this container:

⁠Docker with a config file.

Make a config.json file for the application, and then launch the uchiwa container with the config mounted as a volume.

# Create a folder that will be mount as a volume to the Docker container
mkdir ~/uchiwa-config
# Copy your uchiwa config into this last folder
cp ~/uchiwa/config.json ~/uchiwa-config/config.json
# Start Docker container. It will listen on port 3000 by default
docker run -v ~/uchiwa-config:/config uchiwa/uchiwa

⁠Docker with environment variables

You can instead use environment variables to configure the application. Host is fixed to 0.0.0.0 and port to 3000, but the other settings can be set:

• UCHIWA_USER
• UCHIWA_PASS
• UCHIWA_REFRESH

And configuring an API is done with other environment variables which are designed to fit into Docker's container links (allowing you to point uchiwa at an API just be --linking it to that container)

You can link multiple APIs by providing multiple sets of environment variables with different prefixes.

These variables are mandatory.

• API1_PORT_4567_TCP_PORT - The port for the API, usually 4567
• API1_PORT_4567_TCP_ADDR - The hostname or IP for the API

These variables are optional

• API1_UCHIWA_NAME
• API1_UCHIWA_SSL
• API1_UCHIWA_USER
• API1_UCHIWA_PASS
• API1_UCHIWA_PATH
• API1_UCHIWA_TIMEOUT

An example of starting the container with the minimum set of environment needed would be:

docker run -i -t -p 3000 -e API1_PORT_4567_TCP_PORT=3000 -e API1_PORT_4567_TCP_ADDR="1.1.1.1" uchiwa/uchiwa

⁠Debugging

You may start the dashboard with the following command in order to enable verbose mode: NODE_ENV="development" node app.js

⁠Health

You may easily monitor Uchiwa and the Sensu API endpoints with the /health page.

⁠/health

Returns Uchiwa and Sensu API status.

• success: 200
  • content: {"uchiwa":"ok","sensu":{"0.12.6":{"output":"ok"},"0.13.0":{"output":"ok"}}}
• error: 503
  • content: {"uchiwa":"ok","sensu":{"0.12.6":{"output":"connect ECONNREFUSED"},"0.13.0":{"output":"ok"}}}

⁠/health/uchiwa

Returns Uchiwa status.

• success: 200
  • content: {"uchiwa":"ok"}
• error: 503
  • content: {"uchiwa":"error"}

⁠/health/sensu

Returns Sensu API status.

• success: 200
  • content: {"sensu":{"0.12.6":{"output":"ok"},"0.13.0":{"output":"ok"}}}
• error: 503
  • content: {"sensu":{"0.12.6":{"output":"connect ECONNREFUSED"},"0.13.0":{"output":"ok"}}}

⁠Contributing

Everyone is welcome to submit patches. Whether your pull request is a bug fix or introduces new classes or functions to the project, we kindly ask that you include tests for your changes. Even if it's just a small improvement, a test is necessary to ensure the bug is never re-introduced.

⁠Testing

You should always run npm test before submitting a Pull Request.

⁠E2E testing

1. Clone this⁠ cookbook (git clone [email protected]:palourde/uchiwa-sensu.git)
2. Boot the virtual machines (vagrant up)
3. Copy the configuration file (config.json) found on the uchiwa-sensu repo into the uchiwa repo
4. Install all dependencies (npm install)
5. Run E2E tests (npm run protractor)

⁠Authors

• Author: Simon Plourde⁠ ([email protected]⁠)
• Contributor: Justin Kolberg⁠
• Contributor: ayan4m1⁠
• Contributor: Ethan Hann⁠ ([email protected]⁠)

⁠License

MIT (see LICENSE⁠)