docker-elk: a Compose template for running the Elastic stack locally

What docker-elk is for, and who should skip it

Getting Elasticsearch, Logstash and Kibana talking to each other by hand is mostly a credentials problem. You install three services, create the internal users Kibana and Logstash need, assign roles, then discover that one password is wrong and the whole chain is silent. docker-elk removes that step. The repository is a Compose file plus per-service configuration directories (elasticsearch/, kibana/, logstash/) that build on the official Docker images from Elastic. The README describes the goal in one line: make the Elastic stack as easy as possible to get into.

The audience is narrow on purpose. This suits someone evaluating Elasticsearch's search and aggregation capabilities, or someone who wants Kibana dashboards over a sample dataset without provisioning a cluster. It does not suit a team that needs a hardened, multi-node, monitored deployment, because the project explicitly says it is not a blueprint for a production-ready deployment but a template that promotes tweaking. That distinction is not marketing hedging. The same README disables Elasticsearch bootstrap checks to make development setup easier and points production users at Elasticsearch's own system configuration instructions. If you need TLS between nodes, the README notes a separate tls branch where encryption is enabled in Elasticsearch, Kibana and Fleet.

The setup service and the .env password contract

The mechanism that separates docker-elk from a hand-written Compose file is the setup service. It belongs to a non-default Compose profile, so docker compose up does not start it. You run it by name. It executes a one-off script that creates the Elasticsearch users docker-elk expects, including logstash_internal and kibana_system, with passwords read from the .env file, and it creates the roles those users need. The README states this task is performed only during initial startup; running it again resets existing users' passwords to the .env values and returns built-in roles to their default permissions.

That reset behaviour is the sharpest edge in the project. The docker-compose.yml comment spells it out, and it means the setup service is not a repair tool. If you rotated the elastic password through the API and later re-run setup, you will overwrite your change. The service also runs with network_mode set to the elasticsearch service and depends on it, so it cannot execute before Elasticsearch is reachable.

Configuration flows in three directions. Elasticsearch reads from elasticsearch/, Kibana from kibana/config/kibana.yml, and Logstash from logstash/. The .env file at the repository root supplies ELASTIC_VERSION and the passwords passed into the setup container, including LOGSTASH_INTERNAL_PASSWORD and KIBANA_SYSTEM_PASSWORD. Nothing here is generated for you: the defaults are changeme, and the README treats that as the starting point, not a secret.

Installing docker-elk and reaching the Kibana UI

The prerequisites are Docker Engine 18.06.0 or newer, Docker Compose 2.0.0 or newer, and 1.5 GB of RAM. On Linux, your user needs permission to talk to the Docker daemon. Clone the repository onto the host that will run the stack:

git clone https://github.com/deviantony/docker-elk.git

Run the one-off setup service first. It initializes the Elasticsearch users and roles described above, and it must complete without error before the rest of the stack is useful:

docker compose up setup

The README calls generating Kibana encryption keys optional but highly recommended. This command prints keys that you copy into kibana/config/kibana.yml:

docker compose up kibana-genkeys

Then start the remaining services. Add -d to run them detached in the background:

docker compose up

Give Kibana about a minute, then open http://localhost:5601 and log in as elastic with the password changeme. The stack exposes 5044 for the Logstash Beats input, 50000 for the Logstash TCP input, 9600 for the Logstash monitoring API, 9200 and 9300 for Elasticsearch HTTP and transport, and 5601 for Kibana. One warning from the README is easy to miss: rebuild the images with docker compose build whenever you switch branch or change the version of an existing stack.

Where docker-elk stops being the right tool

The licence behaviour is the first limitation. Platinum features are enabled by default for a 30-day trial. After that period the README says you keep the free Open Basic features without manual intervention and without losing data, but if you want to opt out of the trial from the start, you have to follow the README's section on disabling paid features. Teams that cannot run trial software in their environment need to make that change before the first start, not after.

Bootstrap checks are disabled. That is a deliberate choice for development hosts, and it means the container will start on a machine that Elasticsearch would otherwise refuse. Do not read a successful docker compose up as evidence that the host is configured correctly.

The default single-node layout is another boundary. The README includes a section on scaling out the Elasticsearch cluster, so the path exists, but the shipped configuration is one node with one Elasticsearch container. If your workload is already asking for replica shards and node roles, you are past the template's starting point and into Elasticsearch operations.

Finally, the project's stated philosophy is documentation over automation, with a minimal and unopinionated default configuration. That is a real trade-off. You get few surprises in the Compose file and a lot of manual editing when you need anything beyond the defaults.

How docker-elk differs from Grafana and from managed Elasticsearch

The comparison people reach for is Grafana. The two tools answer different questions. Grafana is a visualization layer that queries data sources you already run; it does not ship a storage engine or an ingest pipeline. docker-elk brings its own storage and ingest: Elasticsearch holds and indexes the data, Logstash transforms it, and Kibana reads from Elasticsearch. If your data already lives in Prometheus or a SQL database and you only need dashboards, Grafana plus that source is the shorter path. If you need full-text search and aggregations over documents you are about to ingest, docker-elk gives you the storage side as well.

Managed Elasticsearch is the other alternative, and the difference is operational rather than functional. A hosted service takes over node provisioning, upgrades and snapshots. docker-elk hands all of that back to you, in exchange for running entirely on your own hardware with no external dependency during the initial setup. That property is why the project exists: the README notes the initial setup relies on no external dependency and uses as little scripting as necessary. The cost is that every upgrade is your problem, and the README's warning about rebuilding images after a version change is the first place you will feel it.

Maintenance, upgrades and the MIT licence

The repository is not archived and the last push was on 2026-09-20, so the project is being touched. That does not make upgrades cheap. Version selection is a documented topic, and the README's warning is explicit: rebuild the stack images with docker compose build whenever you switch branch or update the version of an existing stack. ELASTIC_VERSION in .env drives the image tags, so an upgrade is a .env edit plus a rebuild, plus whatever configuration changes the new Elasticsearch, Logstash or Kibana release requires in the per-service directories. The project does not automate that migration, by design.

The repository is MIT licensed, which covers the Compose file, the setup scripts and the configuration in this repository. It does not cover the Elastic images the stack pulls, and those carry their own licence terms, including the trial behaviour described above. The README links to Elastic's subscription and licence management documentation rather than restating the terms. Read those before you decide whether the trial default is acceptable in your environment; this article is not legal advice.

Editorial conclusion

Adopt docker-elk if you want a working Elasticsearch, Logstash and Kibana trio on one host to learn the query language, prototype a dashboard or inject sample data. Do not adopt it as a production blueprint: the README states it is a template, bootstrap checks are disabled, and the default passwords in .env are changeme. Before you commit, verify that Docker Compose is version 2.0.0 or newer, that the host has 1.5 GB of RAM free, and whether you want to run docker compose up kibana-genkeys and paste the output into kibana/config/kibana.yml or accept the stack without generated encryption keys.

Frequently asked questions

Official sources

1. deviantony/docker-elk on GitHub
2. Issues
3. License: MIT
4. README
5. Releases