Upgrade Graylog in Docker only after the backends and the supported path are planned
Upgrading a Graylog stack running in Docker Compose touches three things at once: the Graylog server containers, the MongoDB container that holds configuration and metadata, and the search backend that stores your logs, which is Graylog Data Node or self-managed OpenSearch. Graylog advises moving one minor version at a time and taking backups of Graylog, MongoDB and Data Node data before you change any image tag. Teams usually upgrade for three reasons: to receive security fixes, to stay on a release Graylog still supports, and to gain features they need for detection or investigation work. Each reason is weaker than it looks if the upgrade breaks ingestion or search, so the plan should start with the target version, not the image pull.
Graylog's upgrade documentation covers Docker installations alongside its Ubuntu, Red Hat, Debian and SUSE package procedures, so the Docker path follows the same supported sequence rather than a separate community recipe. Before you touch the Compose file, confirm three things: the target minor version in the Graylog upgrade documentation, the MongoDB versions that release supports in the compatibility matrix, and the Data Node or OpenSearch versions it accepts. Graylog 7.0 to 7.2 need MongoDB 7.x up to 8.2.x, and OpenSearch 1.x is deprecated since Graylog 7.0 and removed in Graylog 8.0, so an older backend can force a backend upgrade first. Write down the upgrade stops you will take between your current version and the target, and confirm each against the release notes for that version.
What changes in Graylog 7 that affects a Docker upgrade
This table lists the Graylog 7 changes that touch a Docker Compose stack, from runtime and database prerequisites to the search backend. Read each row against the compatibility matrix and release notes for your exact target version, because requirements can differ between 7.0, 7.1 and 7.2.
| Change | Impact on a Docker stack | Action needed |
|---|---|---|
| Java 21 runtime | The Graylog server image runs on the Java version it ships with, so custom images or host-level Java overrides can conflict after the upgrade. | Confirm the Java version in the target image tag and remove any custom Java base layers or overrides. |
| MongoDB 7.0 minimum | The MongoDB container must be at least 7.0 before Graylog 7 starts, and older MongoDB images will not work with the new server. | Plan MongoDB upgrades in stepped versions first and check the supported range in the compatibility matrix. |
| MongoDB supported range up to 8.2.x | MongoDB images newer than the supported range may be outside what Graylog documents, even if they start. | Pin the MongoDB image tag to a version listed in the compatibility matrix for your target Graylog release. |
| OpenSearch 1.x deprecation | Stacks still using an OpenSearch 1.x container receive a deprecation status, and removal is planned for Graylog 8.0. | Inventory the search container and plan a move to Graylog Data Node or a supported OpenSearch version. |
| Graylog Data Node recommendation | Graylog recommends Data Node as the search backend, so a new Data Node container and its certificates and volumes may need adding to Compose. | Confirm the Data Node image tag and configuration for your target release in the installation docs. |
| Graylog 7.2 release line | The current documentation covers 7.2, so Compose files copied from older examples may reference outdated tags or settings. | Check the release notes for 7.2 and any patch release you target before editing image tags. |
| Compatibility matrix and release notes | Exact supported versions for the Graylog server, MongoDB, Data Node and OpenSearch depend on the target release. | Read the compatibility matrix for your target version and record the tags you will pin before the upgrade window. |
Which MongoDB and search backend versions Graylog accepts
Graylog recommends Data Node as the search backend, so most Docker Compose stacks planning an upgrade will target it. Data Node is Graylog's own storage layer for log data, and the compatibility matrix is the authority for which Data Node build pairs with which Graylog server release. Do not assume the Data Node tag follows the Graylog tag. Confirm the pairing for your target version before you change anything.
- Target release first: Graylog 7.0 to 7.2 are the releases covered by the MongoDB and backend ranges in the compatibility matrix, so start from the version you intend to run.
- Data Node is the recommended path: Graylog's installation docs position Data Node as the recommended search backend for new and migrated stacks.
- Confirm the image tag: Look up the exact Data Node image tag for your target release in the Graylog docs and in your own container registry mirror.
- Mirror before you pull: If you run an air-gapped or registry-restricted environment, copy the confirmed image to your registry and reference that tag in the Compose file.
- Check the data path: Data Node holds the indices, so confirm the volume it writes to before the image changes.
Before you edit the Compose file, check the compatibility matrix for the target Graylog version and record the Data Node tag you have confirmed.
If your stack still runs OpenSearch, the compatibility matrix lists support from 1.1.x up to 3.7.x for Graylog 7.0 to 7.2. Graylog Security needs OpenSearch 2.0 or later, so a stack that uses Graylog Security cannot stay on OpenSearch 1.x. Use of OpenSearch 1.x has been deprecated since Graylog 7.0 and will be removed in Graylog 8.0, which means an OpenSearch 1.x stack must move during this upgrade cycle rather than later.
- Deprecation timing: OpenSearch 1.x use is deprecated since Graylog 7.0 and will be removed in Graylog 8.0, so plan the backend move now.
- Graylog Security requirement: Graylog Security needs OpenSearch 2.0 or later, so confirm your edition before choosing a version.
- Supported range: The matrix lists OpenSearch from 1.1.x up to 3.7.x for Graylog 7.0 to 7.2. Pick a patch tag within that range.
- Confirm the image tag: Check the exact OpenSearch image tag in the Graylog docs and in your own registry.
- Plan the index compatibility: Moving between OpenSearch major versions changes index handling, so test the upgrade path against a copy of your data.
Confirm the OpenSearch tag against the compatibility matrix and your Graylog Security requirements before editing the Compose file.
MongoDB holds Graylog configuration and metadata, and it is independent of the search backend choice. For Graylog 7.0 to 7.2, the compatibility matrix supports MongoDB 7.x up to 8.2.x. Because MongoDB must match the Graylog target release, a stack on an older MongoDB major needs a stepwise path, and that path belongs in the plan before the Graylog image changes.
- Supported range: MongoDB 7.x up to 8.2.x is the range listed for Graylog 7.0 to 7.2.
- Stepwise moves: Move MongoDB one supported major at a time, verifying the cluster between steps.
- Replica set state: For multi-node designs, the recommended layout uses MongoDB as a replica set, so confirm the set is healthy before any change.
- Confirm the image tag: Check the exact MongoDB image tag in the Graylog docs and in your own registry.
- Back up first: Graylog advises backing up Graylog, MongoDB and Data Node data before upgrading.
Record the MongoDB tag and the upgrade sequence in your change plan, then verify it against the compatibility matrix for the target Graylog version.
The three containers are not upgraded independently of one another. The compatibility matrix describes the combination that works for each Graylog release, so the check is a set check rather than three separate lookups. Record one table that lists the Graylog, Data Node or OpenSearch, and MongoDB tags for the current and target releases, then confirm each row against the matrix.
- One table, three columns: Write the current and target tag for Graylog, the search backend and MongoDB side by side.
- Check the matrix for the target only: The matrix describes compatible combinations for a given release, so start there.
- Confirm the tags in the docs: Verify each exact tag in the Graylog docs and your own registry before editing the Compose file.
- Pin versions in the file: Use explicit tags rather than floating labels so the stack does not change on the next pull.
- Re-check after any change: If the target moves to a different minor release, repeat the table check.
Do not edit the Compose file until the table has been checked against the matrix for the target version.
Compatibility is confirmed on paper before the stack starts, and the first start is the moment to check that the running versions match the table. Verification is a step you can run against the live containers, so the team sees the exact versions Graylog reports rather than relying on the file alone. This tab covers what to check after the new images are in place and before logs are routed through the upgraded stack.
- Read the running versions: Use the Graylog system pages and the container image output to confirm each component reports the target version.
- Check the backend health: Confirm the search backend reports a healthy cluster before Graylog writes to it.
- Confirm MongoDB connectivity: Confirm Graylog can read and write its configuration after restart.
- Keep the old images: Retain the previous tags so you can roll back the Compose file if a check fails.
- Record the result: Save the confirmed versions with the change record for audit and support.
Before you consider the upgrade complete, confirm that every container reports the version in your table.
Backups and inventory to finish before the first container restarts
Every item here gives you a way back if the upgrade fails partway through. Backups protect the data, the inventory tells you what the upgrade can break, and the staging copy and rollback plan let you test both before production containers change.
Graylog config and MongoDB backups
Back up the Graylog configuration file and the MongoDB data that holds users, streams, inputs, pipelines and dashboards. Take a MongoDB dump or filesystem snapshot from the running replica set while Graylog is stopped or quiesced, and record the MongoDB version in use. Confirm the backup works by restoring it into a scratch container and checking that a known stream, a user login and a dashboard load. A backup you have not restored is an assumption.
Data Node and index snapshot repositories
Register a snapshot repository for Data Node or OpenSearch indices in storage outside the Compose stack, then take a snapshot of every index set you need to keep. Store the repository settings and the path to the storage location with the upgrade record. Restore one non-critical index into the staging stack to prove the snapshot is usable. Volume copies of search data are not a substitute for snapshots taken through the search backend.
Compose file, environment and certificates
Copy the docker-compose.yml, every .env file, and the TLS certificates and keys into version control or an encrypted backup. Record the exact image tags currently running for Graylog, Data Node and MongoDB, since the upgrade changes these tags. Keep the password secret and the password_secret value unchanged, because the stack cannot read stored data without it. Check the file permissions on the copies.
Inventory of customizations
List every plugin jar, content pack, pipeline rule, dashboard, event definition, lookup table and script that calls the Graylog API. Note which API endpoints and token types each script uses. Mark anything built against a Graylog API or plugin interface that the upgrade notes change, so it is reviewed before the containers restart rather than after alerts stop firing.
Staging copy from the same Compose file
Build a staging stack from the same Compose file and the same restored backups, then run the upgrade there first. Use the same image tags you plan to deploy, and keep staging on a network that cannot reach production log sources or send alert notifications. Use staging to measure how long the upgrade takes on your data volume and to check that inputs, searches and dashboards behave as expected.
Written rollback plan with a named owner
Write the rollback steps before the change window: which previous image tags to restore, which volumes and backups to reattach, the order in which to bring back MongoDB, Data Node and Graylog, and the decision point at which rollback starts. Name one owner who can call the rollback and one person who can execute it. Confirm that the owner can reach the people who approve changes during the window.
Docker Compose upgrade sequence, one minor version at a time
This sequence moves a Docker Compose Graylog stack through one minor version at a time, with a check and a rollback point at every stage so the cluster is known healthy before the next pass begins.
Confirm the target version and read its release notes
Before touching the stack, confirm the next minor version you will move to and read the upgrade notes for that release in the Graylog upgrade documentation. Note the MongoDB and search backend versions the target needs, and whether the release changes parsing, API behavior or plugin requirements. Your check is a written upgrade plan for this one pass that names the source version, target version, and the image tags for Graylog, MongoDB and Data Node. Rollback point: nothing has changed yet, so you can stop here at no cost.
Stop inputs and drain the journal
Pause or stop the inputs that send traffic to Graylog, or redirect senders to a buffer you control, so no new messages arrive during the pass. Then wait for the message journal to drain to zero on each node using the Graylog system views. Your check is that the journal is empty and the input counts have flatlined on every node. If the journal does not drain, investigate the cause before continuing, because unprocessed messages will sit in the journal across the upgrade. Rollback point: restarting the inputs returns the stack to its prior state.
Back up Graylog, MongoDB and Data Node data
Take a backup of each data layer before changing any image tag. Back up the MongoDB data volume or run a MongoDB dump, export the Graylog server configuration files and the Compose file, and take a Data Node snapshot or volume copy for the search data. Store the copies outside the Docker host. Your check is that each backup completes without errors and that you can list its contents or restore it to a scratch environment. This backup is your rollback point for the rest of the pass.
Upgrade MongoDB first when the target requires it
If the target Graylog version requires a newer MongoDB, change the MongoDB image tag in the Compose file and bring up only the MongoDB container, following the replica set upgrade order that the MongoDB documentation describes for your topology. Keep Graylog stopped during this step. Your check is that MongoDB reports a healthy primary and that the Graylog server can still reach it once you restart it later. If the target does not need a MongoDB change, record that decision and move on. Rollback point: restore the MongoDB volume from the backup and revert the image tag.
Upgrade the search backend when required
If the target release requires a newer Data Node version, change its image tag and start the Data Node container alone. Let the cluster reach a green or healthy status before continuing, and confirm the Data Node version matches the compatibility matrix for the target Graylog release. Graylog recommends Data Node as the search backend, and OpenSearch 1.x use is deprecated since Graylog 7.0. Your check is the cluster health reported by Data Node and the Graylog system page showing the search backend as connected. Rollback point: restore the Data Node snapshot and revert the tag.
Change the Graylog image tag on every node
Update the Graylog image tag in the Compose file to the target minor version on every Graylog node, then recreate the containers. Keep one node as the leader and leave follower nodes with is_leader set to false, as the multi-node guidance requires. Do not start a second minor version on any node until all nodes match. Your check is that the Compose file and running containers show the same image tag on all nodes. Rollback point: revert the tag and recreate the containers using the prior image, provided the backups from earlier are intact.
Start containers and watch the startup logs
Start the Graylog containers and follow the logs of each node through startup. Look for errors about database schema migrations, plugin loading, certificate or configuration problems, and connection failures to MongoDB or the search backend. Wait until each node reports that the web interface and the input subsystem are running. Your check is a clean startup log on every node with no repeated exceptions. Rollback point: if a node fails to start in a way you cannot resolve, stop it and restore from backup rather than letting it run in a mixed state.
Confirm node health and restart inputs
Once every node is running on the target version, confirm each node is healthy in the system overview, check that the journal is not growing, and restart inputs one at a time while watching throughput. Verify that search, dashboards and event definitions still return results. Only after this check passes should you begin the next minor version, which is a separate pass through this entire sequence. Your check is steady journal depth, expected message counts and no new errors. If health degrades, pause inputs again and use the backups to return to the prior version.
How to confirm the journal drains after restart and roll back a failed step
After every restart of a Graylog container, check the message journal before you treat the upgrade step as finished. Inputs resume as soon as the node is up, so a node that has restarted cleanly should drain its journal back toward zero once processing catches up. The Graylog system architecture guidance sizes the journal at three to five times daily ingest on SSDs, so you can estimate how much buffered data a healthy node should hold at peak. A journal that keeps growing after inputs resume means the node is not keeping up, and that is the signal to stop and investigate rather than move to the next container.
Read the journal and node state in the Graylog web interface on the System pages, where the node list and per-node journal figures appear, and cross-check them in the container logs with docker compose logs graylog. Confirm the exact views, labels and log messages for your version in the Graylog upgrade documentation, because the names of these pages change between releases. Check that every upgraded node has rejoined the cluster, that the journal trend is downward, and that the Data Node and MongoDB containers report healthy. If one node does not rejoin, inspect its startup logs for configuration errors, such as a data_dir or MongoDB connection problem, before you retry.
Decide between reverting and restoring before you change anything else. If the new image fails to start but the volumes were not written to, pinning the previous image tag in the docker-compose.yml file and recreating the container is usually the fastest rollback. If the upgrade ran a schema or data migration, or the MongoDB or Data Node volumes were altered, revert the image only after you have restored the volumes from the backup you took beforehand. Confirm with Graylog support or the upgrade notes for your exact versions which migrations are not reversible. Record each rollback step and the restored backup timestamp so the next attempt starts from a known state.
What makes a Docker upgrade take longer
This table lists the factors that stretch a Graylog Docker upgrade and what each one changes in effort. Read each row against your own stack before you ask a partner for a quote or set a change window. The main takeaway is that node count, index data volume and the number of dependent integrations usually matter more than the image pull itself.
| Driver | Effect on effort | What to check |
|---|---|---|
| Graylog nodes and MongoDB topology | Each node is upgraded in turn, and a non-replica-set MongoDB leaves no failover path during the change | Confirm the node count, whether MongoDB runs as a replica set, and that every node will run the same image tag |
| Index data size and restore time | Backup and restore of OpenSearch or Data Node volumes often dominates the window, and it grows with retained data | Measure total index size from your retention settings and test a restore on a copy of the volume before the change |
| Plugins and in-house extensions | Custom plugins may need rebuilding or retesting against the new release before the stack can start | List every plugin in the mounted plugin directory and confirm each one has a build for the target version |
| API clients and scripts | Automation that calls changed endpoints or sends strict JSON breaks silently after the upgrade | Inventory scripts, CI jobs and integrations that call the Graylog API and review the upgrade notes for each endpoint they use |
| Parsing rules and dashboards | A changed field name or default can alter extractors, pipelines, streams and dashboards that depend on it | Export pipeline rules, streams and dashboards, then compare query results on staging before production |
| Environments (development, staging, production) | Each environment needs its own backup, upgrade run and verification, so effort scales with the count | Confirm which environments exist, their versions, and whether staging holds production-like data volumes |
| Air-gapped or restricted networks | Images, packages and plugin artifacts must be mirrored into the network before any container can be pulled | Confirm the image tags for Graylog, Data Node and MongoDB, and who approves each mirrored artifact |
What buyers ask before hiring help with a Graylog Docker upgrade
What drives the cost of a Graylog Docker upgrade and what should a quote list?
The main cost driver is how much the stack differs from a standard Compose file and how many versions you must cross. Effort rises with the number of Graylog nodes, the MongoDB and Data Node versions involved, custom plugins, pipelines, content packs and the number of inputs and dashboards that must be verified afterward. A quote should list the written scope, each version step, the backup and rollback approach, the staging run, the production window, the verification checks and the documentation handed over. Ask whether the quote covers one-time upgrade work only or also a later retainer for support. DeployOpen does not publish prices, so the quote follows from the agreed scope.
Can our own team run a Graylog Docker upgrade without outside help?
Yes, a team with Docker Compose, MongoDB and Graylog operations experience can run it, provided it follows Graylog's upgrade documentation and works one minor version at a time. The risk is less in the commands than in the checks: confirming that the MongoDB and Data Node versions match the compatibility matrix for each step, verifying parsing and API consumers, and proving that the journal drains after each restart. If nobody on the team has done a multi-version Graylog upgrade before, an outside review of the plan and the staging run reduces the chance of a rollback in production.
How long does a Graylog Docker upgrade take and what sets the duration?
Duration depends on the number of version steps, the size of the MongoDB and Data Node data that must be backed up and restored, how many containers restart in sequence, and how long the journal takes to drain after each restart. It also depends on the time needed to validate inputs, dashboards, event definitions and API integrations. Staging rehearsals add time but usually shorten the production window. Ask the provider to state the number of steps, the rehearsal plan and the agreed maintenance window in the written scope before work starts, since no duration figure is supplied for this topic.
What does the upgrade need from our team before work starts?
The work needs access to the Docker host or hosts, the Compose file and environment files, and the registry or image source used for the Graylog, Data Node and MongoDB tags. It needs a backup window and a staging copy that matches production as closely as practical. Your team should name owners for inputs, streams, pipelines, dashboards and event definitions, because those owners confirm behavior after each step. Someone must also approve the production window and the rollback decision. Confirm backup storage, retention and who can restore data before the window opens.
Does Graylog Open or Graylog Enterprise change the Docker upgrade steps?
The core sequence of backups, one minor version at a time, compatible MongoDB and Data Node versions and post-restart checks is the same for both editions. Edition matters for what you verify afterward. Graylog Enterprise and Graylog Security add features such as the data lake, correlation engine, Okta, OpenID Connect and SAML sign-in, and SIEM content, so those need their own checks. Graylog Open is licensed under SSPL-1.0, which is not an OSI-approved open source license, and that licensing question is separate from the upgrade steps. Confirm your edition and the features in use before scoping.
What happens if a Graylog Docker upgrade fails partway through?
A sound plan defines the rollback point before the first change. That means verified backups of Graylog configuration in MongoDB, Data Node or OpenSearch indices and the Compose files, plus the exact image tags that were running before the change. If a step fails, the team stops, returns to the previous tags and restores data only if the backup check confirms it is needed. Failed steps should be recorded with logs and the cause. Ask the provider how it handles a failed step, who makes the rollback decision and how long the system can be paused during recovery.
Can DeployOpen run the Graylog Docker upgrade and document the result?
DeployOpen plans, implements, backs up, upgrades, documents and supports self-hosted open-source platforms inside your own infrastructure, so it can run a Graylog Docker upgrade in your environment under a fixed scope agreed in writing. The handover typically covers the versions before and after each step, the backup records, the verification results for inputs, the journal checks and the changes made to configuration. DeployOpen does not issue audit reports or certifications, so any compliance evidence it produces is readiness material for your auditors to review.
How DeployOpen scopes and delivers a Graylog Docker upgrade
DeployOpen starts by reading your running Compose stack, its image tags and its volumes, then agrees a written scope before any change is made. The work is planned around the upgrade path you need, tested on a copy of your environment, and handed over with runbooks your team can follow.
How we scope
- Inventory the Compose file, image tags for Graylog, Data Node and MongoDB, and the named volumes holding their data.
- Confirm the current version and the target minor release, and plan the one-minor-version-at-a-time path Graylog documents.
- Agree the written scope, deliverables and timeline in advance, with the backup and rollback steps included.
How we build
- Take and verify backups of Graylog, MongoDB and Data Node data before any image tag is changed.
- Rehearse each step in a non-production copy of your stack, recording the container order and the checks at each stop.
- Confirm that inputs keep writing to the journal during restarts and that the journal drains after each Graylog container returns.
How we hand over
- Deliver a runbook with the exact upgrade order, image tags, volume list and rollback procedure for your environment.
- Document the post-upgrade checks, including journal drain status, index health and input status, for your team to repeat.
- Walk your operators through the runbook so the next minor upgrade can be run by your own staff.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, scoped separately from the upgrade project.
- Retainers can cover the next Graylog minor release and the review of breaking changes that apply to your parsing rules and API clients.
- Support runs in your own infrastructure, so your data and credentials stay under your control throughout.
