fleet/README.md

Kolide

Contents

• Development Environment
  • Installing build dependencies
  • Building
    • Generating the packaged JavaScript
    • Compiling the kolide binary
    • Managing Go dependencies with glide
    • Automatic recompilation
  • Testing
    • Application tests
    • Viewing test coverage
    • Testing email
  • Development Infrastructure
    • Starting the local development environment
    • Stopping the local development environment
    • Setting up the database tables
  • Running Kolide

Development Environment

Installing build dependencies

To setup a working local development environment, you must install the following minimum toolset:

• Docker
• Go (1.6 or greater)
• Node.js (and npm)
• GNU Make

Once you have those minimum requirements, to install build dependencies, run the following:

make deps

Building

Generating the packaged JavaScript

To generate all necessary code (bundling JavaScript into Go, etc), run the following:

make generate

Compiling the kolide binary

Use go build to build the application code. For your convenience, a make command is included which builds the code:

make build

It's not necessary to use Make to build the code, but using Make allows us to account for cross-platform differences more effectively than the go build tool when writing automated tooling. Use whichever you prefer.

Managing Go Dependencies with Glide

Glide is a package manager for third party Go libraries. See the "How It Works" section in the Glide README for full details.

Installing the correct versions of dependencies

To install the correct versions of third package libraries, use glide install. glide install will use the glide.lock file to pull vendored packages from remote vcs. make deps takes care of this step, as well as downloading the latest version of glide for you.

Adding new dependencies

To add a new dependency, use glide get [package name]

Updating dependencies

To update, use glide up which will use VCS and glide.yaml to figure out the correct updates.

Testing application code with glide

Testing

Application tests

You can use go test $(glide novendor) to run the go unit tests and skip tests in the vendor directory. This will run go test over all directories of your project except the vendor directory.

To execute all of the tests that CI will execute, run the following from the root of the repository:

make test

Viewing test coverage

When you run make test from the root of the repository, test coverage reports are generated in every subpackage. For example, the sessions subpackage will have a coverage report generated in ./sessions/sessions.cover

To explore a test coverage report on a line-by-line basis in the browser, run the following:

# substitute ./datastore/datastore.cover, etc
go tool cover -html=./server/server.cover

To view test a test coverage report in a terminal, run the following:

# substitute ./datastore/datastore.cover, etc
go tool cover -func=./server/server.cover

Testing Email

To intercept sent emails while running a Kolide development environment, make sure that you've set the SMTP address to <docker host ip>:1025 and leave the username and password blank. Then, visit <docker host ip>:8025 in a web browser to view the MailHog UI.

For example, if docker is running natively on your localhost, then your mail settings should look something like:

{
  "mail": {
    "address": "localhost:1025",
    "pool_connections": 4
  }
}

Development infrastructure

Starting the local development environment

To set up a canonical development environment via docker, run the following from the root of the repository:

docker-compose up

This requires that you have docker installed. At this point in time, automatic configuration tools are not included with this project.

Stopping the local development environment

If you'd like to shut down the virtual infrastructure created by docker, run the following from the root of the repository:

docker-compose down

Setting up the database tables

Once you docker-compose up and are running the databases, you can build the code and run the following command to create the database tables:

kolide prepare db

Running Kolide

Now you are prepared to run a Kolide development environment. Run the following:

kolide serve

If you're running the binary from the root of the repository, where it is built by default, then the binary will automatically use the provided example configuration file, which assumes that you are running docker locally, on localhost via a native engine.

You may have to edit the example configuration file to use the output of docker-machine ip instead of localhost if you're using Docker via Docker Toolbox.