Skip to content

Added: STOP_SERVER_DELAY_COMMAND #4109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
itzg merged 2 commits into from
Jun 16, 2026
+13 −2
Merged

Added: STOP_SERVER_DELAY_COMMAND #4109

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ce036bf
Added: STOP_SERVER_DELAY_COMMAND
jameswagnerjr Jun 15, 2026
a967506
Revert formatting changes
jameswagnerjr Jun 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 15 additions & 9 deletions docs/configuration/misc-options.md
View file
Open in desktop
Comment thread
itzg marked this conversation as resolved.
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,12 @@ If this behavior interferes with the log content, then disable TTY or remove the

To allow time for players to finish what they're doing during a graceful server shutdown, set `STOP_SERVER_ANNOUNCE_DELAY` to a number of seconds to delay after an announcement is posted by the server.

To set a custom command to run at the start of this delay period, set `STOP_SERVER_DELAY_COMMAND` to the full command. This will run in place of the announcement.

!!! warning "Increase stop grace period"

The Docker stop grace period must be increased to a value longer than the announce delay. The value to use that is longer than announce delay will vary based upon the amount of time it takes for final world data saving. If the container exits with exit code 137, then that indicates a longer grace period is needed.
The Docker stop grace period must be increased to a value longer than the announce delay. The value to use that is longer than announce delay will vary based upon the amount of time it takes for final world data saving. If the container exits with exit code 137, then that indicates a longer grace period is needed.

The grace period can be increased using [the -t option on `docker compose down`](https://docs.docker.com/compose/reference/down/) or set the [stop_grace_period](https://docs.docker.com/compose/compose-file/05-services/#stop_grace_period) in the compose file.

The `STOP_SERVER_ANNOUNCE_DELAY` can be bypassed by sending a `SIGUSR1` signal to the `mc-server-runner` process.
Expand Down Expand Up @@ -98,11 +100,13 @@ Set the environment variable `GENERATE_LOG4J2_CONFIG` to "true" to enable the fo
You can customize various aspects of the logging behavior using environment variables:

- `LOG_LEVEL` : Root logger level (default: `info`)

```
-e LOG_LEVEL=debug
```

- `ROLLING_LOG_FILE_PATTERN` : Pattern for rolled log file names (default: `logs/%d{yyyy-MM-dd}-%i.log.gz`)

```
-e ROLLING_LOG_FILE_PATTERN="logs/archive/%d{yyyy-MM-dd}-%i.log.gz"
```
Expand All @@ -128,6 +132,7 @@ For full control over how log messages are formatted, you can customize the Log4
### Example configurations

Simple timestamp customization (most common use case):

```yaml
environment:
# What you see in docker logs
Expand All @@ -137,6 +142,7 @@ environment:
```

Advanced customization:

```yaml
environment:
LOG_LEVEL: debug
Expand Down Expand Up @@ -191,14 +197,14 @@ Be sure to also increase the shutdown timeout described [here for docker compose

## Setup only

If you are using a host-attached data directory, then you can have the image setup the Minecraft server files and stop prior to launching the server process by setting `SETUP_ONLY` to `true`.
If you are using a host-attached data directory, then you can have the image setup the Minecraft server files and stop prior to launching the server process by setting `SETUP_ONLY` to `true`.

## Enable Flare Flags

To enable the JVM flags required to fully support the [Flare profiling suite](https://blog.airplane.gg/flare), set the following variable:

-e USE_FLARE_FLAGS=true

Flare is built-in to Pufferfish/Purpur, and is available in [plugin form](https://github.com/TECHNOVE/FlarePlugin) for other server types.

## Enable support for optimized SIMD operations
Expand Down Expand Up @@ -227,8 +233,8 @@ environment:

The files will be downloaded to `/data/` relative paths, so `plugins/WorldEdit` will be saved as `/data/plugins/WorldEdit/config.yml`.

!!! note
The downloaded files can be further processed using [environment variable replacement](interpolating.md) or [patch definitions](interpolating.md#patching-existing-files)
!!! note
The downloaded files can be further processed using [environment variable replacement](interpolating.md) or [patch definitions](interpolating.md#patching-existing-files)

@itzg itzg Jun 16, 2026

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The indent was important here for the admonition


## Enable timestamps in init logs

Expand Down
226 changes: 115 additions & 111 deletions docs/variables.md
View file
Open in desktop
Comment thread
itzg marked this conversation as resolved.
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@

!!! warning

The variables listed on this page are manually documented and may be out-of-date or inaccurate.

All other documentation pages are actively maintained, so please use the search box above to find the desired topic.

### General options

<table>
<thead>
<tr>
Expand Down Expand Up @@ -53,113 +53,114 @@
alternatively, you can mount: <code>/etc/localtime:/etc/localtime:ro

/etc/timezone:/etc/timezone:ro</code>
</td>
<td><code>UTC</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_LEVEL</code></td>
<td>Root logger level (trace, debug, info, warn, error)</td>
<td><code>info</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_CONSOLE_FORMAT</code></td>
<td>Log4j2 pattern for console output (what you see in <code>docker logs</code>)</td>
<td><code>[%d{HH:mm:ss}] [%t/%level]: %msg%n</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_FILE_FORMAT</code></td>
<td>Log4j2 pattern for file logs (written to <code>logs/latest.log</code>)</td>
<td><code>[%d{HH:mm:ss}] [%t/%level]: %msg%n</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_TERMINAL_FORMAT</code></td>
<td>Log4j2 pattern for interactive terminal console (used with <code>docker attach</code>)</td>
<td><code>[%d{HH:mm:ss} %level]: %msg%n</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>ROLLING_LOG_FILE_PATTERN</code></td>
<td>Pattern for rolled/archived log file names</td>
<td><code>logs/%d{yyyy-MM-dd}-%i.log.gz</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>ROLLING_LOG_MAX_FILES</code></td>
<td>Maximum number of archived log files to keep</td>
<td><code>1000</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>ENABLE_ROLLING_LOGS</code></td>
<td><strong>Legacy option.</strong> Rolling logs are now enabled by default via templated log4j2 configuration. This option is maintained for backward compatibility but only used for error reporting</td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>ENABLE_JMX</code></td>
<td>To enable remote JMX, such as for profiling with VisualVM or JMC, add the environment variable ENABLE_JMX=true</td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>JMX_HOST</code></td>
<td>If JMX is enabled, set JMX_HOST to the IP/host running the Docker container, and add a port forwarding of TCP port 7091</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>USE_AIKAR_FLAGS</code></td>
<td><a href="https://aikar.co/2018/07/02/tuning-the-jvm-g1gc-garbage-collector-flags-for-minecraft/">Aikar has done some research</a> into finding the optimal JVM flags for GC tuning, which becomes more important as more users are connected concurrently</td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>USE_MEOWICE_FLAGS</code></td>
<td><a href="https://github.com/MeowIce/meowice-flags?tab=readme-ov-file#why-would-i-have-to-switch-">MeowIce has created an updated set of JVM flags</a> based on Aikar's flags but with support for optimizations for Java 17 and above</td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>USE_MEOWICE_GRAALVM_FLAGS</code></td>
<td>enables MeowIce's flags for GraalVM if USE_MEOWICE_GRAALVM_FLAGS is TRUE</td>
<td><code>true</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>JVM_OPTS</code></td>
<td>General JVM options can be passed to the Minecraft Server invocation by passing a <code>JVM_OPTS</code> environment variable. The JVM requires -XX options to precede -X options, so those can be declared in <code>JVM_XX_OPTS</code>. Both variables are space-delimited, raw JVM arguments</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>JVM_XX_OPTS</code></td>
<td>General JVM options can be passed to the Minecraft Server invocation by passing a <code>JVM_OPTS</code> environment variable. The JVM requires -XX options to precede -X options, so those can be declared in <code>JVM_XX_OPTS</code>. Both variables are space-delimited, raw JVM arguments</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>JVM_DD_OPTS</code></td>
<td>As a shorthand for passing several system properties as -D arguments, you can instead pass a comma separated list of name=value or name:value pairs with JVM_DD_OPTS. (The colon syntax is provided for management platforms like Plesk that don't allow = inside a value.)</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>EXTRA_ARGS</code></td>
<td>Arguments that would usually be passed to the jar file (those which are written after the filename)</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_TIMESTAMP </code></td>
<td>To include the timestamp with each log set to <code>true</code></td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
</tbody>
</td>
<td><code>UTC</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_LEVEL</code></td>
<td>Root logger level (trace, debug, info, warn, error)</td>
<td><code>info</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_CONSOLE_FORMAT</code></td>
<td>Log4j2 pattern for console output (what you see in <code>docker logs</code>)</td>
<td><code>[%d{HH:mm:ss}] [%t/%level]: %msg%n</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_FILE_FORMAT</code></td>
<td>Log4j2 pattern for file logs (written to <code>logs/latest.log</code>)</td>
<td><code>[%d{HH:mm:ss}] [%t/%level]: %msg%n</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_TERMINAL_FORMAT</code></td>
<td>Log4j2 pattern for interactive terminal console (used with <code>docker attach</code>)</td>
<td><code>[%d{HH:mm:ss} %level]: %msg%n</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>ROLLING_LOG_FILE_PATTERN</code></td>
<td>Pattern for rolled/archived log file names</td>
<td><code>logs/%d{yyyy-MM-dd}-%i.log.gz</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>ROLLING_LOG_MAX_FILES</code></td>
<td>Maximum number of archived log files to keep</td>
<td><code>1000</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>ENABLE_ROLLING_LOGS</code></td>
<td><strong>Legacy option.</strong> Rolling logs are now enabled by default via templated log4j2 configuration. This option is maintained for backward compatibility but only used for error reporting</td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>ENABLE_JMX</code></td>
<td>To enable remote JMX, such as for profiling with VisualVM or JMC, add the environment variable ENABLE_JMX=true</td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>JMX_HOST</code></td>
<td>If JMX is enabled, set JMX_HOST to the IP/host running the Docker container, and add a port forwarding of TCP port 7091</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>USE_AIKAR_FLAGS</code></td>
<td><a href="https://aikar.co/2018/07/02/tuning-the-jvm-g1gc-garbage-collector-flags-for-minecraft/">Aikar has done some research</a> into finding the optimal JVM flags for GC tuning, which becomes more important as more users are connected concurrently</td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>USE_MEOWICE_FLAGS</code></td>
<td><a href="https://github.com/MeowIce/meowice-flags?tab=readme-ov-file#why-would-i-have-to-switch-">MeowIce has created an updated set of JVM flags</a> based on Aikar's flags but with support for optimizations for Java 17 and above</td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>USE_MEOWICE_GRAALVM_FLAGS</code></td>
<td>enables MeowIce's flags for GraalVM if USE_MEOWICE_GRAALVM_FLAGS is TRUE</td>
<td><code>true</code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>JVM_OPTS</code></td>
<td>General JVM options can be passed to the Minecraft Server invocation by passing a <code>JVM_OPTS</code> environment variable. The JVM requires -XX options to precede -X options, so those can be declared in <code>JVM_XX_OPTS</code>. Both variables are space-delimited, raw JVM arguments</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>JVM_XX_OPTS</code></td>
<td>General JVM options can be passed to the Minecraft Server invocation by passing a <code>JVM_OPTS</code> environment variable. The JVM requires -XX options to precede -X options, so those can be declared in <code>JVM_XX_OPTS</code>. Both variables are space-delimited, raw JVM arguments</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>JVM_DD_OPTS</code></td>
<td>As a shorthand for passing several system properties as -D arguments, you can instead pass a comma separated list of name=value or name:value pairs with JVM_DD_OPTS. (The colon syntax is provided for management platforms like Plesk that don't allow = inside a value.)</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>EXTRA_ARGS</code></td>
<td>Arguments that would usually be passed to the jar file (those which are written after the filename)</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>LOG_TIMESTAMP </code></td>
<td>To include the timestamp with each log set to <code>true</code></td>
<td><code>false</code></td>
<td>⬜️</td>
</tr>
</tbody>

</table>

### Server
Expand Down Expand Up @@ -246,6 +247,12 @@ alternatively, you can mount: <code>/etc/localtime:/etc/localtime:ro
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>STOP_SERVER_DELAY_COMMAND</code></td>
<td>To set a custom command to run at the start of this delay period, set <code>STOP_SERVER_DELAY_COMMAND</code> to the full command. This will run in place of the announcement.</td>
<td><code></code></td>
<td>⬜️</td>
</tr>
<tr>
<td><code>PROXY</code></td>
<td>You may configure the use of an HTTP/HTTPS proxy by passing the proxy's URL</td>
Expand Down Expand Up @@ -505,8 +512,6 @@ This image maps known server properties as described in [this section](configura
</tbody>
</table>



### Auto-Stop

!!! note
Expand Down Expand Up @@ -556,7 +561,6 @@ This image maps known server properties as described in [this section](configura
</tbody>
</table>


### CurseForge

!!! tip
Expand Down
3 changes: 3 additions & 0 deletions scripts/start-finalExec
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -481,6 +481,9 @@ fi
if [[ ${STOP_SERVER_ANNOUNCE_DELAY} ]]; then
mcServerRunnerArgs+=(--stop-server-announce-delay "${STOP_SERVER_ANNOUNCE_DELAY}s")
fi
if [[ ${STOP_SERVER_DELAY_COMMAND} ]]; then
mcServerRunnerArgs+=(--stop-server-delay-command "${STOP_SERVER_DELAY_COMMAND}s")
fi
if isTrue "${ENABLE_SSH}"; then
mcServerRunnerArgs+=(--remote-console)
fi
Expand Down