From 5a5e60489a8f8d56a176e44128b60226754f7efe Mon Sep 17 00:00:00 2001 From: tony Date: Tue, 18 Aug 2015 08:53:06 +0200 Subject: [PATCH] Updated project documentation. Reviewed how configuration is managed for Kibana to be uniform for all components. --- README.md | 84 ++++++++++++++----- docker-compose.yml | 4 +- elasticsearch/config/.placeholder | 1 + kibana/Dockerfile | 1 - .../config}/logstash.conf | 0 5 files changed, 65 insertions(+), 25 deletions(-) create mode 100644 elasticsearch/config/.placeholder rename {logstash-conf => logstash/config}/logstash.conf (100%) diff --git a/README.md b/README.md index b7fb6dd..1076e5e 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Based on the official images: * [logstash](https://registry.hub.docker.com/_/logstash/) * [kibana](https://registry.hub.docker.com/_/kibana/) -# HOW TO +# Requirements ## Setup @@ -20,52 +20,90 @@ Based on the official images: 2. Install [Docker-compose](http://docs.docker.com/compose/install/). 3. Clone this repository -### SELinux +## SELinux On distributions which have SELinux enabled out-of-the-box you will need to either re-context the files or set SELinux into Permissive mode in order for fig-elk to start properly. For example on Redhat and CentOS, the following will apply the proper context: -``` +````bash .-root@centos ~ -`-$ chcon -R system_u:object_r:admin_home_t:s0 fig-elk/ -``` +-$ chcon -R system_u:object_r:admin_home_t:s0 fig-elk/ +```` -## Usage +# Usage -### Start the stack and inject logs +Start the ELK stack using *docker-compose*: -First step, you can edit the logstash-configuration in *logstash-conf/logstash.conf*. You can add filters you want to test for example. - -Then, start the ELK stack using *docker-compose*: - -``` +```bash $ docker-compose up ``` You can also choose to run it in background (detached mode): -``` +```bash $ docker-compose up -d ``` Now that the stack is running, you'll want to inject logs in it. The shipped logstash configuration allows you to send content via tcp: -``` +```bash $ nc localhost 5000 < /path/to/logfile.log ``` +And then access Kibana UI by hitting [http://localhost:5601](http://localhost:5601) with a web browser. -### Playing with the stack - -The stack exposes 3 ports on your localhost: - +By default, the stack exposes the following ports: * 5000: Logstash TCP input. * 9200: Elasticsearch HTTP (with Marvel plugin accessible via [http://localhost:9200/_plugin/marvel](http://localhost:9200/_plugin/marvel)) -* 5601: Kibana 4 web interface, access it via [http://localhost:5601](http://localhost:5601) +* 5601: Kibana 4 web interface +*WARNING*: If you're using *boot2docker*, you must access it via the *boot2docker* IP address instead of *localhost*. -### Boot2docker +# Configuration -If you're using *boot2docker*, you must access it via the *boot2docker* IP address: -* http://boot2docker-ip-address:9200/_plugin/marvel to access the Marvel plugin. -* http://boot2docker-ip-address:5601 to use Kibana 4. +*NOTE*: Configuration is not dynamically reloaded, you will need to restart the stack after any change in the configuration of a component. + +## How can I tune Kibana configuration? + +The Kibana default configuration is stored in `kibana/config/kibana.yml`. + +## How can I tune Logstash configuration? + +The logstash configuration is stored in `logstash/config/logstash.conf`. + +The folder `logstash/config` is mapped onto the container `/etc/logstash/conf.d` so you +can create more than one file in that folder if you'd like to. However, you must be aware that config files will be read from the directory in alphabetical order. + +## How can I tune Elasticsearch configuration? + +The Elasticsearch container is using the shipped configuration and it is not exposed by default. + +If you want to override the default configuration, create a file `elasticsearch/config/elasticsearch.yml` and add your configuration in it. + +Then, you'll need to map your configuration file inside the container in the `docker-compose.yml`. Update the elasticsearch container declaration to: + +```yml +elasticsearch: + build: elasticsearch/ + ports: + - "9200:9200" + volumes: + - ./elasticsearch/config/elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml +``` + +# Storage + +## How can I store Elasticsearch data? + +In order to persist Elasticsearch data, you'll have to mount a volume on your Docker host. Update the elasticsearch container declaration to: + +```yml +elasticsearch: + build: elasticsearch/ + ports: + - "9200:9200" + volumes: + - /path/to/storage:/usr/share/elasticsearch/data +``` + +This will store elasticsearch data inside `/path/to/storage`. diff --git a/docker-compose.yml b/docker-compose.yml index 55da656..15a9681 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -6,13 +6,15 @@ logstash: image: logstash:latest command: logstash -f /etc/logstash/conf.d/logstash.conf volumes: - - logstash-conf:/etc/logstash/conf.d + - ./logstash/config:/etc/logstash/conf.d ports: - "5000:5000" links: - elasticsearch kibana: build: kibana/ + volumes: + - ./kibana/config/kibana.yml:/opt/kibana/config/kibana.yml ports: - "5601:5601" links: diff --git a/elasticsearch/config/.placeholder b/elasticsearch/config/.placeholder new file mode 100644 index 0000000..9ad2662 --- /dev/null +++ b/elasticsearch/config/.placeholder @@ -0,0 +1 @@ +Ensure the existence of the parent folder. diff --git a/kibana/Dockerfile b/kibana/Dockerfile index 902d228..609fa37 100644 --- a/kibana/Dockerfile +++ b/kibana/Dockerfile @@ -2,7 +2,6 @@ FROM kibana:latest RUN apt-get update && apt-get install -y netcat -COPY config/kibana.yml /opt/kibana/config/kibana.yml COPY entrypoint.sh /tmp/entrypoint.sh RUN chmod +x /tmp/entrypoint.sh diff --git a/logstash-conf/logstash.conf b/logstash/config/logstash.conf similarity index 100% rename from logstash-conf/logstash.conf rename to logstash/config/logstash.conf