Merge branch 'feature/docker' into 'master'

Feature/docker

See merge request grafolean/grafolean-collector-snmp!4

Author: grafolean

.dockerignore

@@ -0,0 +1,5 @@
+.git
+.env*
+.vscode
+.pytest_cache
+

.gitlab-ci.yml

@@ -0,0 +1,43 @@
+image: docker:stable
+
+services:
+  - docker:dind
+
+variables:
+  DOCKER_DRIVER: overlay2
+
+stages:
+  - test
+  - deploy
+
+pytest:
+  stage: test
+  image: python:3.6-slim-stretch
+  before_script:
+    - apt-get update
+    - apt-get install --no-install-recommends -q -y libsnmp-dev build-essential
+    - pip install --no-cache-dir pipenv
+    - pipenv install --dev
+  script:
+    - pipenv run pytest -x test_snmpcollector.py
+
+deploy to docker hub:
+  stage: deploy
+  when: manual
+  only:
+    variables:
+      - $CI_COMMIT_TAG =~ /^v[0-9]+[.][0-9]+[.][0-9]+([.][^.]+)?$/
+  variables:
+    CI_REGISTRY_IMAGE: grafolean/grafolean-collector-snmp
+  script:
+    - apk add --no-cache git
+    # check that we are deploying the latest version:
+    - export LAST_KNOWN_VERSION=`git tag -l --sort=-version:refname "v*.*.*" | head -n 1 | tr -d '[:space:]'`
+    - '[ "$LAST_KNOWN_VERSION" == "$CI_COMMIT_TAG" ] || (echo "Tag does not denote latest known version (which is $LAST_KNOWN_VERSION), aborting!" && exit 1)'
+    - echo "Deploying..."
+    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
+    - docker build -t "docker.io/$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG" -t "docker.io/$CI_REGISTRY_IMAGE:latest" --build-arg VERSION=$CI_COMMIT_TAG --build-arg VCS_REF=$CI_COMMIT_SHA --build-arg BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ') .
+    - docker push "docker.io/$CI_REGISTRY_IMAGE:$CI_COMMIT_TAG"
+    - docker push "docker.io/$CI_REGISTRY_IMAGE:latest"
+    - docker rmi $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG
+    - docker rmi $CI_REGISTRY_IMAGE:latest

Dockerfile

@@ -0,0 +1,43 @@
+FROM python:3.6-slim-stretch as python-requirements
+COPY ./Pipfile ./Pipfile.lock /snmpcollector/
+WORKDIR /snmpcollector
+RUN \
+    pip install pipenv && \
+    pipenv lock -r > /requirements.txt
+
+FROM python:3.6-slim-stretch as build-backend
+COPY ./ /snmpcollector/
+WORKDIR /snmpcollector
+RUN \
+    find ./ ! -name '*.py' -type f -exec rm '{}' ';' && \
+    rm -rf tests/ .vscode/ .pytest_cache/ __pycache__/ && \
+    python3.6 -m compileall -b ./ && \
+    find ./ -name '*.py' -exec rm '{}' ';'
+
+
+FROM python:3.6-slim-stretch
+ARG VERSION
+ARG VCS_REF
+ARG BUILD_DATE
+LABEL org.label-schema.vendor="Grafolean" \
+      org.label-schema.url="https://grafolean.com/" \
+      org.label-schema.name="Grafolean SNMP Collector" \
+      org.label-schema.description="SNMP collector for Grafolean" \
+      org.label-schema.version=$VERSION \
+      org.label-schema.vcs-url="https://gitlab.com/grafolean/grafolean-collector-snmp/" \
+      org.label-schema.vcs-ref=$VCS_REF \
+      org.label-schema.build-date=$BUILD_DATE \
+      org.label-schema.docker.schema-version="1.0"
+COPY --from=python-requirements /requirements.txt /requirements.txt
+RUN \
+    apt-get update && \
+    apt-get install --no-install-recommends -q -y libsnmp-dev build-essential&& \
+    pip install --no-cache-dir -r /requirements.txt && \
+    apt-get purge -y build-essential && \
+    apt-get clean autoclean && \
+    apt-get autoremove --yes && \
+    rm -rf /var/lib/{apt,dpkg,cache,log}/ && \
+    echo "alias l='ls -altr'" >> /root/.bashrc
+COPY --from=build-backend /snmpcollector/ /snmpcollector/
+WORKDIR /snmpcollector
+CMD ["python", "-m", "snmpcollector"]

README.md

@@ -0,0 +1,61 @@
+# About Grafolean SNMP Collector
+
+This package is a SNMP Collector for Grafolean, an easy to use generic monitoring system.
+
+Once installed, all the configuration of SNMP sensors is done through Grafolean's web-based user interface. Depending on permissions,
+a single SNMP Collector instance can be fetching data for multiple accounts and entities. The fetching intervals can be specified with
+up to a second precision.
+
+Under the hood it uses [net-snmp](http://net-snmp.sourceforge.net/) (via [easysnmp](https://easysnmp.readthedocs.io)), which means
+it should be compatible with any device that can respond to requests by `snmpget` and `snmpwalk`.
+
+Requirements:
+- the devices that should be queried via SNMP must be accessible *from the container* (make sure SNMP Collector is installed in correct network and that there are no firewalls in between)
+- Grafolean must be accessible via HTTP(S)
+
+Current limitations:
+- does not yet support out-of-order SNMP WALK responses
+- does not yet limit the maximum number of retrieved OIDs when doing SNMP WALK
+- BULK GET/WALK is not supported yet
+
+# License
+
+License is Commons Clause license (on top of Apache 2.0) - source is available, you can use it for free (commercially too), modify and
+share, but you can't sell it. See [LICENSE.md](https://gitlab.com/grafolean/grafolean-collector-snmp/blob/master/LICENSE.md) for details.
+
+If in doubt, please [open an issue](https://gitlab.com/grafolean/grafolean-collector-snmp/issues) to get further clarification.
+
+# Install (docker / docker-compose)
+
+This is the easiest and currently the only officially supported way. However other installation methods should be straightforward by studying `Dockerfile`.
+
+1) log in to Grafolean service (either https://grafolean.com/ or self-hosted), select an appropriate `Account` and create a new `Bot`. Make sure that selected protocol is `SNMP`. Copy the bot token.
+2) save [docker-compose.yml](https://gitlab.com/grafolean/grafolean-collector-snmp/raw/master/docker-compose.yml) to a local file
+3) edit `docker-compose.yml` and change:
+    - mandatory: `BACKEND_URL` (set to the URL of Grafolean backend, for example `https://grafolean.com/api`),
+    - mandatory: `BOT_TOKEN` (set to the bot token from step 1),
+    - optional: `JOBS_REFRESH_INTERVAL` (interval in seconds at which the jobs definitions will be updated)
+   Alternatively, you can also copy `.env.example` to `.env` and change settings there (leaving `docker-compose.yml` in original state).
+4) run: `docker-compose up -d`
+
+## Upgrade
+
+1) `docker-compose pull`
+2) `docker-compose down && docker-compose up -d`
+
+## Debugging
+
+Container logs can be checked by running:
+```
+$ docker logs grafolean-collector-snmp
+```
+
+# Development
+
+## Contributing
+
+To contribute to this repository, CLA needs to be signed. Please open an issue about the problem you are facing before submitting a pull request.
+
+## Issues
+
+If you encounter any problems installing or running the software, please let us know in the [issues](https://gitlab.com/grafolean/grafolean-collector-snmp/issues). If possible, please make sure to describe the issue in a way that will allow us to reproduce it.

docker-compose.yml

@@ -0,0 +1,31 @@
+version: '2.1'
+services:
+
+  #
+  # Welcome to Grafolean SNMP Collector!
+  #
+  # This file should be modified to suit your running environment. Please check the comments and change
+  # the settings appropriately.
+  #
+
+  snmpcollector:
+    # If you wish to load an explicit version, change the next line. For example:
+    #   image: grafolean/grafolean-collector-snmp:v1.0.0
+    image: grafolean/grafolean-collector-snmp
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: grafolean-collector-snmp
+    environment:
+      # Backend url must be set to the address of the Grafolean backend, for example this uses Grafolean hosted service:
+      # - BACKEND_URL=https://grafolean.com/api
+      - BACKEND_URL=${BACKEND_URL}
+      # To use SNMP Collector, a bot with the protocol "snmp" must be added via user interface, then the token needs to be copied here:
+      - BOT_TOKEN=${BOT_TOKEN}
+      # Interval between fetching information about jobs:
+      - JOBS_REFRESH_INTERVAL=${JOBS_REFRESH_INTERVAL}
+    restart: always
+    # Grafolean backend must be accessible on BACKEND_URL *from the point of view of container*. If running
+    # on the same host, '127.0.0.1' translates to container, not host - this directive changes network mode
+    # so that Docker networking is bypassed.
+    #network_mode: "host"