Merge pull request #10 from deviantony/enhanced-documentation

Updated project documentation.

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`.

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:

elasticsearch/config/.placeholder

@@ -0,0 +1 @@
+Ensure the existence of the parent folder.

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