diff --git a/docs/INSTALL_MANUAL.md b/docs/INSTALL_MANUAL.md index 8b13789..3c7f7a4 100644 --- a/docs/INSTALL_MANUAL.md +++ b/docs/INSTALL_MANUAL.md @@ -1 +1,148 @@ +# Manual Install +While the easiest way to get started with [Scrutiny is using Docker](https://github.com/AnalogJ/scrutiny#docker), +it is possible to run it manually without much work. You can even mix and match, using Docker for one component and +a manual installation for the other. + +Scrutiny is made up of two components: a collector and a webapp/api. Here's how each component can be deployed manually. + +## Webapp/API + +### Dependencies + +Since the webapp is packaged as a stand alone binary, there isn't really any software you need to install other than `glibc` +which is included by most linux OS's already. + + +### Directory Structure + +Now let's create a directory structure to contain the Scrutiny files & binary. + +``` +mkdir -p /etc/scrutiny/config +mkdir -p /etc/scrutiny/web +mkdir -p /etc/scrutiny/bin +``` + +### Config file + +While it is possible to run the webapp/api without a config file, the defaults are designed for use in a container environment, +and so will need to be overridden. So the first thing you'll need to do is create a config file that looks like the following: + +``` +# stored in /etc/scrutiny/config/scrutiny.yaml + +version: 1 + +web: + database: + # The Scrutiny webapp will create a database for you, however the parent directory must exist. + location: /etc/scrutiny/config/scrutiny.db + src: + frontend: + # The path to the Scrutiny frontend files (js, css, images) must be specified. + # We'll populate it with files in the next section + path: /etc/scrutiny/web +``` + +> Note: for a full list of available configuration options, please check the [example.scrutiny.yaml](https://github.com/AnalogJ/scrutiny/blob/master/example.scrutiny.yaml) file. + +### Download Files + +Next, we'll download the Scrutiny API binary and frontend files from the [latest Github release](https://github.com/analogj/scrutiny/releases). +The files you need to download are named: + +- **scrutiny-web-linux-amd64** - save this file to `/etc/scrutiny/bin` +- **scrutiny-web-frontend.tar.gz** - save this file to `/etc/scrutiny/web` + +### Prepare Scrutiny + +Now that we have downloaded the required files, let's prepare the filesystem. + +``` +# Let's make sure the Scrutiny webapp is executable. +chmod +x /etc/scrutiny/bin/scrutiny-web-linux-amd64 + +# Next, lets extract the frontend files. +cd /etc/scrutiny/web +tar xvzf scrutiny-web-frontend.tar.gz --strip-components 1 -C . + +# Cleanup +rm -rf scrutiny-web-frontend.tar.gz +``` + +### Start Scrutiny Webapp + +Finally, we start the Scrutiny webapp: + +``` +/etc/scrutiny/bin/scrutiny-web-linux-amd64 start --config /etc/scrutiny/config/scrutiny.yaml +``` + +The webapp listens for traffic on `http://0.0.0.0:8080` by default. + + +## Collector + +### Dependencies + +Unlike the webapp, the collector does have some dependencies: + +- `smartctl`, v7+ +- `cron` (or an alternative process scheduler) + +Unfortunately the version of `smartmontools` (which contains `smartctl`) available in some of the base OS repositories is ancient. +So you'll need to install the v7+ version using one of the following commands: + +- **Ubuntu:** `apt-get install -y smartmontools=7.0-0ubuntu1~ubuntu18.04.1` +- **Centos8:** + - `dnf install https://extras.getpagespeed.com/release-el8-latest.rpm` + - `dnf install smartmontools` + + +### Directory Structure + +Now let's create a directory structure to contain the Scrutiny collector binary. + +``` +mkdir -p /etc/scrutiny/bin +``` + + +### Download Files + +Next, we'll download the Scrutiny collector binary from the [latest Github release](https://github.com/analogj/scrutiny/releases). +The file you need to download is named: + +- **scrutiny-collector-metrics-linux-amd64** - save this file to `/etc/scrutiny/bin` + + +### Prepare Scrutiny + +Now that we have downloaded the required files, let's prepare the filesystem. + +``` +# Let's make sure the Scrutiny collector is executable. +chmod +x /etc/scrutiny/bin/scrutiny-collector-metrics-linux-amd64 +``` + +### Start Scrutiny Collector, Populate Webapp + +Next, we will manually trigger the collector, to populate the Scrutiny dashboard: + +``` +/etc/scrutiny/bin/scrutiny-collector-metrics-linux-amd64 run --api-endpoint "http://localhost:8080" +``` + +### Schedule Collector with Cron + +Finally you need to schedule the collector to run periodically. +This may be different depending on your OS/environment, but it may look something like this: + +``` +# open crontab +crontab -e + +# add a line for Scrutiny +*/15 * * * * /etc/scrutiny/bin/scrutiny-collector-metrics-linux-amd64 run --api-endpoint "http://localhost:8080" +```