Clarify README installation instructions; clean up docker-compose.yml

Author: Anze

README.md

@@ -27,29 +27,53 @@ If in doubt, please [open an issue](https://gitlab.com/grafolean/grafolean-colle
 
 # 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`.
+Docker is the easiest and currently the only officially supported way. Note that while instructions might (with possibly some modifications) work on other operating systems, Linux is assumed.
 
 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
+
+2) save [docker-compose.yml](https://gitlab.com/grafolean/grafolean-collector-snmp/raw/master/docker-compose.yml) to a local file:
+    ```
+    $ mkdir ~/snmpcollector
+    $ cd ~/snmpcollector
+    $ wget https://gitlab.com/grafolean/grafolean-collector-snmp/raw/master/docker-compose.yml
+    ```
+
 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`
 
+If you get no error, congratulations! Everything else is done from within the Grafolean UI. You can however check the status of container as usually by running `docker ps` and investigate logs by running `docker logs -f grafolean-collector-snmp`.
+
+In case of error make sure that the user is allowed to run `docker` (that is, that it is in `docker` group) by running `docker ps`. Alternatively, container can be run using `sudo` (line 4 then reads `sudo docker-compose up -d`).
+
 ## Upgrade
 
-1) `docker-compose pull`
-2) `docker-compose down && docker-compose up -d`
+Upgrading should be easy:
+
+1) `$ docker-compose pull`
+2) `$ docker-compose down`
+3) `$ docker-compose up -d`
 
 ## Debugging
 
 Container logs can be checked by running:
 ```
-$ docker logs grafolean-collector-snmp
+$ docker logs --since 5m -f grafolean-collector-snmp
 ```
 
+## Building locally
+
+If you wish to build the Docker image locally (for debugging or for development purposes), you can specify a custom docker-compose YAML file:
+```
+docker-compose -f docker-compose.dev.yml build
+```
+
+In this case `.env.example` can be copied to `.env` and all settings can be altered there, which helps us avoid commiting settings to the repository.
+
 # Development
 
 ## Contributing
@@ -58,4 +82,4 @@ To contribute to this repository, CLA needs to be signed. Please open an issue a
 
 ## 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.
+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). Please make an effort when describing the issue. If we can reproduce the problem, we can also fix it much faster.

docker-compose.dev.yml

@@ -0,0 +1,34 @@
+version: '2.1'
+services:
+
+  #
+  # Welcome to Grafolean SNMP Collector!
+  #
+  # This file is meant for development purposes only. Please use `docker-compose.yml` for usual installation.
+  #
+  # Feel free to investigate this file (and comments), but the preferred way of changing development settings is to:
+  # - copy .env.example to .env (which is already in .gitignore)
+  # - change the settings in .env
+  #
+
+  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"

docker-compose.yml

@@ -12,18 +12,15 @@ services:
     # 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}
+      - 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}
+      - BOT_TOKEN=
       # Interval between fetching information about jobs:
-      - JOBS_REFRESH_INTERVAL=${JOBS_REFRESH_INTERVAL}
+      - JOBS_REFRESH_INTERVAL=60
     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