diff --git a/.travis.yml b/.travis.yml index 09f8e29d..160ffa71 100644 --- a/.travis.yml +++ b/.travis.yml @@ -24,8 +24,8 @@ before_install: install: - rvm 2.0.0 do gem install --no-document fpm - dep ensure -- docker build -t unifi-poller . -- docker run -d --name unifi-poller unifi-poller | tee docker_id +- make docker +- docker run -d --name unifi-poller golift/unifi-poller | tee docker_id script: # Once we figure out how to keep it running we can remove the -a in ps args. - docker ps -a | grep -q unifi-poller diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c07962c2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,72 @@ +_This doc is far from complete._ + +# Build Pipeline + +Lets talk about how the software gets built for our users before we talk about +making changes to it. + +## TravisCI + +This repo is tested, built and deployed by [Travis-CI](https://travis-ci.org/davidnewhall/unifi-poller). + +The [.travis.yml](.travis.yml) file in this repo coordinates the entire process. +As long as this document is kept up to date, this is what the travis file does: + +- Creates a go-capable build environment on a Linux host, some debian variant. +- Install ruby-devel to get rubygems. +- Installs other build tools including rpm and fpm from rubygems. +- Starts docker, builds the docker container and runs it. +- Tests that the Docker container ran and produced expected output. +- Makes a release. `make release`: This does a lot of things, controlled by the [Makefile](Makefile). + - Runs go tests and go linters. + - Compiles the application binaries for Linux and macOS. + - Compiles a man page that goes into the packages. + - Creates rpm and deb packages using fpm. + - Puts the packages, gzipped binaries and a file containing the SHA256s of each asset into a release folder. + +After the release is built and Docker image tested: +- Deploys the release assets to the tagged release on GitHub using an encrypted GitHub Token (api key). +- Runs [another script](scripts/formula-deploy.sh) to create and upload a Homebrew formula to [golift/homebrew-mugs](https://github.com/golift/homebrew-mugs). + - Uses an encrypted SSH key to upload the updated formula to the repo. +- Travis does nothing else with Docker; it just makes sure the thing compiles and runs. + +### Homebrew + +it's a mac thing. + +[Homebrew](https://brew.sh) is all I use at home. Please don't break the homebrew +formula stuff; it took a lot of pain to get it just right. I am very interested +in how it works for you. + +### Docker + +Docker is built automatically by Docker Cloud using the Dockerfile in the path +[init/docker/Dockerfile](init/docker/Dockerfile). Other than the Dockerfile, all +the configuration is done in the Cloud service under my personal account `golift`. + +If you have need to change the Dockerfile, please clearly explain what problem your +changes are solving, and how it has been tested and validated. As far as I'm +concerned this file should never need to change again, but I'm not a Docker expert; +you're welcome to prove me wrong. + +# Contributing + +Make a pull request and tell me what you're fixing. Pretty simple. If I need to +I'll add more "rules." For now I'm happy to have help. Thank you! + +## Wiki + +**If you see typos, errors, omissions, etc, please fix them.** + +At this point, the wiki is pretty solid. Please keep your edits brief and without +too much opinion. If you want to provide a way to do something, please also provide +any alternatives you're aware of. If you're not sure, just open an issue and we can +hash it out. I'm reasonable. + +## Unifi Library + +If you're trying to fix something in the unifi data collection (ie. you got an +unmarshal error, or you want to add something I didn't include) then you +should look at the [unifi library](https://github.com/golift/unifi). All the +data collection and export code lives there. Contributions and Issues are welcome +on that code base as well. diff --git a/README.md b/README.md index 999283f0..f0a840ee 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ device configuration. This controller can be installed on Windows, macOS and Lin Ubiquiti also provides a dedicated hardware device called a [CloudKey](https://www.ui.com/unifi/unifi-cloud-key/) that runs the controller software. -Unifi-Poller is a smaller application that runs on macOS, Linux or Docker. It +Unifi-Poller is a small application that runs on macOS, Linux or Docker. It polls your controller every 30 seconds for metric data and stores that data in an Influx Database. A small setup with 2 APs, 1 switch, 1 gateway and 40 clients produces nearly 3000 fields (metrics). @@ -28,6 +28,7 @@ graphs to slice the data any way you choose. Good luck! ## Installation [See the Wiki!](https://github.com/davidnewhall/unifi-poller/wiki/Installation) +We have a special place for [Docker Users](https://github.com/davidnewhall/unifi-poller/wiki/Docker). # Backstory @@ -59,9 +60,35 @@ for making this dashboard; it gave me a fantastic start to making my own. I've also created [another forum post](https://community.ubnt.com/t5/UniFi-Wireless/Unifi-Poller-Store-Unifi-Controller-Metrics-in-InfluxDB-without/td-p/2811951) you may use to get additional help. +# Development + +The "What now..." section below used to be a lot larger. I've received a lot of +support, feedback and assistance from the community. Many thanks! This app is +extremely stable with a tiny memory and cpu footprint. I imagine one day we'll +figure out how to make it run on a CloudKey device directly; once I have one +personally that will be my goal. In addition to stability, this app provides +an intuitive installation and configuration process. Maintenance is a breeze too. + +I'm not a software engineer, I'm a a firm believer in operational excellence above +all else. To that end, this app shall remain easy, intuitive and highly adaptable. +I'm totally open to add more configuration options if someone raises a need or concern. + +You can control this app with puppet, chef, saltstack, homebrew or a simple bash +script if you needed to. It's available for macOS, Linux and Docker. It comes with +a systemd service unit that allows you automatically start it up on most Linux +hosts. It probably works just fine on Windows too; +[let me know eh](https://github.com/davidnewhall/unifi-poller/wiki/Windows)? + +The unifi data extraction is provided as an [external library](https://github.com/golift/unifi), +and you can import that code directly without futzing with this application. That +means, if you wanted to do something like make telegraf collect your data instead +of unifi-poller you can achieve that with a little bit of Go code. You could write +a small app that acts as a telegraf input plugin using the available +[unifi](https://github.com/golift/unifi) library to grab the data from your controller. + # What now... -- Are there other devices that need to be included? +### Are there other devices that need to be included? I have: switch, router, access point. Three total, and the type structs are likely missing data for variants of these devices. e.g. Some UAPs have more @@ -70,15 +97,7 @@ ports, some switches have 10Gb, etc. These are things I do not have data on to write code for. If you have these devices, and want them graphed, open an Issue and lets discuss. -- Better Installation instructions. - -If you're a nerd you can probably figure it out. I'd still like some pretty -pictures and maybe even a Twitch VOD. Update: The installation has been -simplified tremendously with the -[creation of binary packages](https://github.com/davidnewhall/unifi-poller/wiki/Installation). -More to come! - -- Radios, Frequencies, Interfaces, vAPs +### Radios, Frequencies, Interfaces, vAPs My access points only seem to have two radios, one interface and vAP per radio. I'm not sure if the graphs, as-is, provide enough insight into APs with other @@ -107,6 +126,6 @@ sites side-by-side. So easy! This screenshot barely does it justice. ## Copyright & License -- Copyright © 2016 Garrett Bjerkhoel. -- Copyright © 2018-2019 David Newhall II. -- See [LICENSE](LICENSE) for license information. +- Copyright © 2016 Garrett Bjerkhoel. +- Copyright © 2018-2019 David Newhall II. +- See [LICENSE](LICENSE) for license information.