The deployment of Graylog within a containerized ecosystem represents a strategic shift toward scalable, maintainable, and portable observability. As a centralized logging solution, Graylog is engineered to aggregate, index, and search massive volumes of log data from diverse sources across an infrastructure. By leveraging Docker and Docker Compose, organizations can abstract the underlying operating system, ensuring that the complex dependencies required for log processing—such as Java runtimes and specific library versions—are encapsulated within a controlled environment. The architecture of Graylog is fundamentally dependent on a triad of services: the Graylog application server, MongoDB for configuration and metadata storage, and OpenSearch (or Elasticsearch) for the indexing and storage of the actual log data. Transitioning this architecture into Docker allows for rapid prototyping, consistent environment parity between development and production, and the ability to scale individual components of the logging pipeline independently.
Architectural Foundations of Graylog in Containers
To understand the deployment of Graylog via Docker, one must first analyze the technical requirements of its architecture. Graylog does not operate as a monolithic entity but as a coordinated system of interdependent services.
The core Graylog application serves as the intelligence layer, providing the web interface, the query language for log searching, and the processing pipelines used for data transformation. In a Dockerized setup, this is typically handled by the graylog/graylog (Open) or graylog/graylog-enterprise images.
The persistence layer is split into two distinct technologies. MongoDB is utilized for the storage of configuration data. This includes user accounts, stream definitions, and alert configurations. Because MongoDB stores the structural state of the system, its availability is critical for the Graylog node to boot and function.
The data indexing layer, facilitated by the Graylog Data Node or an OpenSearch/Elasticsearch cluster, is where the actual log messages reside. This layer is designed for high-throughput writes and complex search queries. In modern Docker deployments, the graylog/graylog-datanode image is used to streamline this process, integrating the indexing capability directly into the Graylog ecosystem.
The interaction between these components occurs over the internal Docker network, ensuring that high-volume traffic between the application server and the data node does not saturate the host's external network interfaces, while providing a secure boundary for administrative traffic.
Technical Specifications and Versioning
The current stable ecosystem for Graylog is centered around version 7.0.6. For production environments, stability is paramount, and the use of the stable 7.0 release is mandatory to ensure reliability and support.
The available tags for the official image allow users to specify the exactness of their deployment:
| Version Tag | Stability Status | Recommended Use Case |
|---|---|---|
| 7.0 | Stable | Production Environments |
| 7.0.6 | Stable | Production Environments |
| 7.0.6-1 | Stable | Production Environments |
| 7.1.0-rc.1-1 | Release Candidate | Testing and Evaluation |
The official Docker image is an automated build, ensuring that the latest patches and security updates are integrated rapidly. The image size is approximately 441.4 MB, which is optimized to balance the inclusion of necessary runtimes with the need for efficient pull times across network boundaries.
From a legal and compliance perspective, the Docker image itself is distributed under the Apache 2.0 license. However, the Graylog software contained within the image is licensed under the Server Side Public License (SSPL), a critical distinction for enterprises managing their software compliance portfolios.
Deployment Prerequisites and System Tuning
Successfully deploying Graylog via Docker Compose requires more than simply running a script; it necessitates specific host-level configurations and administrative familiarity.
The primary technical prerequisite is the installation of a recent version of Docker and Docker Compose. Operators must be proficient in YAML syntax, as the docker-compose.yml file serves as the blueprint for the entire stack, defining networks, volumes, and service dependencies.
A critical system-level requirement involves the Linux kernel's memory mapping. The vm.max_map_count setting must be configured to at least 262144. This is a non-negotiable requirement for the data indexing layer (OpenSearch/Elasticsearch). If this value is too low, the data node will fail to start or crash during high-load indexing operations because it cannot allocate enough memory maps for its indices.
The command to verify and set this value on the host machine is as follows:
bash
sysctl -w vm.max_map_count=262144
To ensure this setting persists across system reboots, it must be added to /etc/sysctl.conf.
Detailed Configuration via Environment Variables
Graylog's Docker image is designed for maximum flexibility, allowing every configuration option to be overridden via environment variables. This approach follows the Twelve-Factor App methodology, separating the configuration from the code.
The naming convention for these variables is strict: the parameter name must be prefixed with GRAYLOG_ and converted to all upper case. For example, a configuration parameter named root_username becomes the environment variable GRAYLOG_ROOT_USERNAME.
Two critical security variables must be defined during the initial deployment to ensure the system is secure and functional:
- GRAYLOGPASSWORDSECRET
This secret is used for password encryption and salting. It must be consistent across all Graylog nodes in a cluster to ensure that passwords can be decrypted and verified regardless of which node handles the request. While the minimum requirement is 16 characters, a length of at least 64 characters is strongly recommended for cryptographic strength. A secure secret can be generated using the following command:
bash
pwgen -N 1 -s 96
- GRAYLOGROOTPASSWORD_SHA2
This variable stores the SHA2 hash of the password for the initial root user. The default username for this account isadmin, though this can be modified usingGRAYLOG_ROOT_USERNAME. Because this password is set via a hash in the environment variable, it cannot be changed via the REST API or the Web interface, making it a critical "break-glass" account for system recovery. A SHA2 hash can be generated via the terminal:
bash
echo -n "Enter Password: " && head -1 </dev/stdin | tr -d '\n' | sha256sum
Implementing Docker Compose for Orchestration
The use of Docker Compose is the recommended method for deploying Graylog as it manages the lifecycle of the multiple required containers. A standard deployment involves the following images:
- MongoDB: The
mongoimage (e.g., version 6.0.18) for configuration storage. - Graylog Data Node: The
graylog/graylog-datanodeimage for log indexing. - Graylog Application: Either
graylog/graylog(Open) orgraylog/graylog-enterprise.
The orchestration process begins with the acquisition of the example docker-compose.yml and the environment.env.example file from the official GitHub repository. These files provide a baseline for services, networks, and volumes.
The impact of using external volumes cannot be overstated. To prevent catastrophic data loss during container restarts or upgrades, external volumes must be configured for:
- MongoDB data directories.
- Graylog Data Node indices.
- Graylog application configuration and data.
By mapping these to the host filesystem, the logs and configurations persist even if the containers are destroyed and recreated.
Advanced Configuration and Remote Management
For organizations that prefer to manage their infrastructure as code (IaC), it is possible to maintain the docker-compose.yml and associated configuration files in a central repository like GitHub.
Inside the Docker container, bundled configuration files are located at /usr/share/graylog/data/config/. To override these with custom versions managed in Git, a dedicated configuration directory must be created on the host.
The process for setting up remote configuration involves the following steps:
- Create a local directory for the configuration.
bash
mkdir -p ./graylog/config
- Navigate into the directory.
bash
cd ./graylog/config
- Download the specific configuration files from the Graylog GitHub repository.
bash
wget https://raw.githubusercontent.com/Graylog2/graylog-docker/6.3/config/graylog.conf
wget https://raw.githubusercontent.com/Graylog2/graylog-docker/6.3/config/log4j2.xml
- Mount the local directory into the container within the
docker-compose.ymlfile.
yaml
services:
mongodb:
image: "mongo:6.0.18"
datanode:
image: "graylog/graylog-datanode:6.3"
graylog:
image: "graylog/graylog-enterprise:6.3"
volumes:
- ./graylog/config:/usr/share/graylog/data/config
This method allows administrators to update the graylog.conf file in Git, push the changes, and simply restart the container to apply new settings, bypassing the need to enter the container via a shell.
Security and Network Optimization
When deploying Graylog in Docker, the principle of least privilege must be applied to network ports. Exposing all available ports to the host increases the attack surface and consumes unnecessary system resources. Only ports required for the specific use case should be mapped.
Typical port requirements include:
- Port 9000: The default port for the Graylog Web Interface.
- Port 1514: The standard port for GELF (Graylog Extended Log Format) input.
- Other custom ports defined for specific inputs (Syslog, HTTP, etc.).
By strictly controlling the ports section of the docker-compose.yml, administrators ensure that the MongoDB and Data Node ports are only accessible to the Graylog application server via the internal Docker network, and not exposed to the public internet or the wider corporate network.
Conclusion
The deployment of Graylog via Docker transforms a complex installation process into a repeatable, automated workflow. By utilizing Docker Compose, the interdependence between the Graylog application, MongoDB, and the Data Node is managed through a single declarative file, ensuring that the system boots in the correct order and with the required network connectivity. The critical nature of the vm.max_map_count setting and the necessity of high-entropy password secrets underscore the technical rigor required for a production-grade deployment.
The flexibility provided by environment variables (prefixed with GRAYLOG_) and the ability to mount external configuration directories from GitHub allow Graylog to fit into modern DevOps pipelines. This setup not only simplifies the initial installation but also provides a robust framework for scaling and disaster recovery. The transition to version 7.0.6 and the use of dedicated data nodes ensure that the system can handle the velocity and volume of modern enterprise logs while maintaining the stability and security required for a central observability platform.