|
1 | | -## Running with a custom server JAR |
2 | | - |
3 | | -If you would like to run a custom server JAR, set `-e TYPE=CUSTOM` and pass the custom server |
4 | | -JAR via `CUSTOM_SERVER`. It can either be a URL or a container path to an existing JAR file. |
5 | | - |
6 | | -If it is a URL, it will only be downloaded into the `/data` directory if it wasn't already. As |
7 | | -such, if you need to upgrade or re-download the JAR, then you will need to stop the container, |
8 | | -remove the file from the container's `/data` directory, and start again. |
9 | | - |
10 | | -## Force re-download of the server file |
11 | | - |
12 | | -For VANILLA, FORGE, BUKKIT, SPIGOT, PAPER, CURSEFORGE, SPONGEVANILLA server types, set |
13 | | -`$FORCE_REDOWNLOAD` to some value (e.g. 'true) to force a re-download of the server file for |
14 | | -the particular server type. by adding a `-e FORCE_REDOWNLOAD=true` to your command-line. |
15 | | - |
16 | | -For example, with PaperSpigot, it would look something like this: |
17 | | - |
18 | | -``` |
19 | | -docker run -d -v /path/on/host:/data \ |
20 | | - -e TYPE=PAPER -e FORCE_REDOWNLOAD=true \ |
21 | | - -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server |
22 | | -``` |
23 | | - |
24 | | -## Running as alternate user/group ID |
25 | | - |
26 | | -By default, the container will switch to and run the Minecraft server as user ID 1000 and group ID 1000; however, that can be changed by setting the environment variables `UID` and `GID`. |
27 | | - |
28 | | -The startup will also skip user switching if the `--user`/`-u` argument is passed to `docker run` or `user` is set on the compose service. |
29 | | - |
30 | | -## Extra Arguments |
31 | | - |
32 | | -Arguments that would usually be passed to the jar file (those which are written after the filename) can be passed via the `EXTRA_ARGS` environment variable. |
33 | | - |
34 | | -See [Custom worlds directory path](../misc/world-data.md#custom-worlds-directory-path) for an example. |
35 | | - |
36 | | -## Interactive and Color Console |
37 | | - |
38 | | -When RCON is enabled, which is the default, and [TTY](https://docs.docker.com/compose/compose-file/05-services/#tty) is enabled on the container, then some server types will output colorized logs and provide a fully interactive console. To access the interactive console, use [`docker attach`](https://docs.docker.com/engine/reference/commandline/container_attach/) (not `exec`). When finished, make sure to use the sequence Control-P, Control-Q to detach without stopping the container. |
39 | | - |
40 | | -If this behavior interferes with the log content, then disable TTY or remove the setting entirely since the default is disabled. In a compose file, set the service's `tty` parameter to `false`. On the `docker run` command-line remove the `-t` argument. |
41 | | - |
42 | | -## Server Shutdown Options |
43 | | - |
44 | | -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. |
45 | | - |
46 | | -!!! warning "Increase stop grace period" |
47 | | - |
48 | | - 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. |
49 | | - |
50 | | - 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. |
51 | | - |
52 | | -The `STOP_SERVER_ANNOUNCE_DELAY` can be bypassed by sending a `SIGUSR1` signal to the `mc-server-runner` process. |
53 | | - |
54 | | -`docker`: |
55 | | - |
56 | | - docker stop --signal SIGUSR1 mc |
57 | | - |
58 | | -`docker compose`: |
59 | | - |
60 | | - docker compose kill --signal SIGUSR1 |
61 | | - |
62 | | -## Configuration Options for Minecraft Server Health Monitoring |
63 | | - |
64 | | -The image tags include specific variables to simplify configuration for monitoring the health of a Minecraft server: |
65 | | - |
66 | | -- `-e SERVER_HOST=localhost` : This variable sets the host address of the Minecraft server to be monitored. By default, it is set to `localhost`, but you can replace it with the actual hostname or IP address of your Minecraft server. |
67 | | - |
68 | | -- `-e SERVER_PORT=25565` : This variable sets the port number on which the Minecraft server is running. By default, Minecraft servers run on port 25565, but if your server is configured to use a different port, you should replace `25565` with the correct port number. This helps the monitoring system to accurately check the health status of the Minecraft server on the specified port. |
69 | | - |
70 | | -## OpenJ9 Specific Options |
71 | | - |
72 | | -The openj9 image tags include specific variables to simplify configuration: |
73 | | - |
74 | | -- `-e TUNE_VIRTUALIZED=TRUE` : enables the option to |
75 | | - [optimize for virtualized environments](https://www.eclipse.org/openj9/docs/xtunevirtualized/) |
76 | | -- `-e TUNE_NURSERY_SIZES=TRUE` : configures nursery sizes where the initial size is 50% |
77 | | - of the `MAX_MEMORY` and the max size is 80%. |
78 | | - |
79 | | -## Enabling rolling logs |
80 | | - |
81 | | -By default the vanilla log file will grow without limit. The logger can be reconfigured to use a rolling log files strategy by using: |
82 | | - |
83 | | -``` |
84 | | - -e ENABLE_ROLLING_LOGS=true |
85 | | -``` |
86 | | - |
87 | | -> **NOTE** this will interfere with interactive/color consoles [as described in the section above](#interactive-and-color-console) |
88 | | -
|
89 | | -## Timezone Configuration |
90 | | - |
91 | | -You can configure the timezone to match yours by setting the `TZ` environment variable: |
92 | | - |
93 | | - -e TZ=Europe/London |
94 | | - |
95 | | -such as: |
96 | | - |
97 | | - docker run -d -it -e TZ=Europe/London -p 25565:25565 --name mc itzg/minecraft-server |
98 | | - |
99 | | -Or mounting `/etc/timezone` as readonly (not supported on Windows): |
100 | | - |
101 | | - -v /etc/timezone:/etc/timezone:ro |
102 | | - |
103 | | -such as: |
104 | | - |
105 | | - docker run -d -it -v /etc/timezone:/etc/timezone:ro -p 25565:25565 --name mc itzg/minecraft-server |
106 | | - |
107 | | -## HTTP Proxy |
108 | | - |
109 | | -You may configure the use of an HTTP/HTTPS proxy by passing the proxy's "host:port" via the environment variable `PROXY`. In [the example compose file](https://github.com/itzg/docker-minecraft-server/blob/master/examples/docker-compose-proxied.yml) it references a Squid proxy. The host and port can be separately passed via the environment variables `PROXY_HOST` and `PROXY_PORT`. A `|` delimited list of hosts to exclude from proxying can be passed via `PROXY_NON_PROXY_HOSTS`. |
110 | | - |
111 | | -## Using "noconsole" option |
112 | | - |
113 | | -Some older versions (pre-1.14) of Spigot required `--noconsole` to be passed when detaching stdin, which can be done by setting `-e CONSOLE=FALSE`. |
114 | | - |
115 | | -## Explicitly disable GUI |
116 | | - |
117 | | -Some older servers get confused and think that the GUI interface is enabled. You can explicitly |
118 | | -disable that by passing `-e GUI=FALSE`. |
119 | | - |
120 | | -## Stop Duration |
121 | | - |
122 | | -When the container is signalled to stop, the Minecraft process wrapper will attempt to send a "stop" command via RCON or console and waits for the process to gracefully finish. By default it waits 60 seconds, but that duration can be configured by setting the environment variable `STOP_DURATION` to the number of seconds. |
123 | | - |
124 | | -## Setup only |
125 | | - |
126 | | -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`. |
127 | | - |
128 | | -## Enable Flare Flags |
129 | | - |
130 | | -To enable the JVM flags required to fully support the [Flare profiling suite](https://blog.airplane.gg/flare), set the following variable: |
131 | | - |
132 | | - -e USE_FLARE_FLAGS=true |
133 | | - |
134 | | -Flare is built-in to Pufferfish/Purpur, and is available in [plugin form](https://github.com/TECHNOVE/FlarePlugin) for other server types. |
135 | | - |
136 | | -## Enable support for optimized SIMD operations |
137 | | - |
138 | | -To enable support for optimized SIMD operations, the JVM flag can be set with the following variable: |
139 | | - |
140 | | - -e USE_SIMD_FLAGS=true |
141 | | - |
142 | | -SIMD optimized operations are supported by Pufferfish and Purpur. |
143 | | - |
144 | | -## Downloading extra configuration files |
145 | | - |
146 | | -You can download additional configuration files or other resources before the server starts by using the `DOWNLOAD_EXTRA_CONFIGS` environment variable. This is useful for downloading configs that you want to patch or modify during the startup process. |
147 | | - |
148 | | -The format uses a `<` separator between the destination path and the source URL: |
149 | | - |
150 | | -``` |
151 | | -DOWNLOAD_EXTRA_CONFIGS=destination<source_url[,destination2<source_url2,...] |
152 | | -``` |
153 | | - |
154 | | -For example, to download configuration files for plugins: |
155 | | - |
156 | | -```yaml |
157 | | -environment: |
158 | | - DOWNLOAD_EXTRA_CONFIGS: | |
159 | | - plugins/WorldEdit<https://raw.githubusercontent.com/EngineHub/WorldEdit/refs/heads/version/7.3.x/worldedit-bukkit/src/main/resources/defaults/config.yml |
160 | | - plugins/EssentialsX<https://raw.githubusercontent.com/EssentialsX/Essentials/refs/heads/2.x/Essentials/src/main/resources/config.yml |
161 | | -``` |
162 | | -
|
163 | | -Or as a single line: |
164 | | -
|
165 | | -```yaml |
166 | | -environment: |
167 | | - DOWNLOAD_EXTRA_CONFIGS: "plugins/WorldEdit<https://example.com/worldedit.yml,config<https://example.com/another.yml" |
168 | | -``` |
169 | | -
|
170 | | -The files will be downloaded to `/data/` relative paths, so `plugins/WorldEdit` will be saved as `/data/plugins/WorldEdit/config.yml`. |
171 | | - |
172 | | -!!! note |
173 | | - The downloaded files can be further processed using [environment variable replacement](interpolating.md) or [patch definitions](interpolating.md#patching-existing-files) |
174 | | - |
175 | | -## Enable timestamps in init logs |
176 | | - |
177 | | -Before the container starts the Minecraft Server its output is prefixed with `[init]`, such as |
178 | | - |
179 | | -``` |
180 | | -[init] Starting the Minecraft server... |
181 | | -``` |
182 | | -
|
183 | | -To also include the timestamp with each log, set `LOG_TIMESTAMP` to "true". The log output will then look like: |
184 | | -
|
185 | | -``` |
186 | | -[init] 2022-02-05 16:58:33+00:00 Starting the Minecraft server... |
187 | | -``` |
| 1 | +## Running with a custom server JAR |
| 2 | + |
| 3 | +If you would like to run a custom server JAR, set `-e TYPE=CUSTOM` and pass the custom server |
| 4 | +JAR via `CUSTOM_SERVER`. It can either be a URL or a container path to an existing JAR file. |
| 5 | + |
| 6 | +If it is a URL, it will only be downloaded into the `/data` directory if it wasn't already. As |
| 7 | +such, if you need to upgrade or re-download the JAR, then you will need to stop the container, |
| 8 | +remove the file from the container's `/data` directory, and start again. |
| 9 | + |
| 10 | +## Force re-download of the server file |
| 11 | + |
| 12 | +For VANILLA, FORGE, BUKKIT, SPIGOT, PAPER, CURSEFORGE, SPONGEVANILLA server types, set |
| 13 | +`$FORCE_REDOWNLOAD` to some value (e.g. 'true) to force a re-download of the server file for |
| 14 | +the particular server type. by adding a `-e FORCE_REDOWNLOAD=true` to your command-line. |
| 15 | + |
| 16 | +For example, with PaperSpigot, it would look something like this: |
| 17 | + |
| 18 | +``` |
| 19 | +docker run -d -v /path/on/host:/data \ |
| 20 | + -e TYPE=PAPER -e FORCE_REDOWNLOAD=true \ |
| 21 | + -p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server |
| 22 | +``` |
| 23 | + |
| 24 | +## Running as alternate user/group ID |
| 25 | + |
| 26 | +By default, the container will switch to and run the Minecraft server as user ID 1000 and group ID 1000; however, that can be changed by setting the environment variables `UID` and `GID`. |
| 27 | + |
| 28 | +The startup will also skip user switching if the `--user`/`-u` argument is passed to `docker run` or `user` is set on the compose service. |
| 29 | + |
| 30 | +## Extra Arguments |
| 31 | + |
| 32 | +Arguments that would usually be passed to the jar file (those which are written after the filename) can be passed via the `EXTRA_ARGS` environment variable. |
| 33 | + |
| 34 | +See [Custom worlds directory path](../misc/world-data.md#custom-worlds-directory-path) for an example. |
| 35 | + |
| 36 | +## Interactive and Color Console |
| 37 | + |
| 38 | +When RCON is enabled, which is the default, and [TTY](https://docs.docker.com/compose/compose-file/05-services/#tty) is enabled on the container, then some server types will output colorized logs and provide a fully interactive console. To access the interactive console, use [`docker attach`](https://docs.docker.com/engine/reference/commandline/container_attach/) (not `exec`). When finished, make sure to use the sequence Control-P, Control-Q to detach without stopping the container. |
| 39 | + |
| 40 | +If this behavior interferes with the log content, then disable TTY or remove the setting entirely since the default is disabled. In a compose file, set the service's `tty` parameter to `false`. On the `docker run` command-line remove the `-t` argument. |
| 41 | + |
| 42 | +## Server Shutdown Options |
| 43 | + |
| 44 | +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. |
| 45 | + |
| 46 | +!!! warning "Increase stop grace period" |
| 47 | + |
| 48 | + 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. |
| 49 | + |
| 50 | + 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. |
| 51 | + |
| 52 | +The `STOP_SERVER_ANNOUNCE_DELAY` can be bypassed by sending a `SIGUSR1` signal to the `mc-server-runner` process. |
| 53 | + |
| 54 | +`docker`: |
| 55 | + |
| 56 | + docker stop --signal SIGUSR1 mc |
| 57 | + |
| 58 | +`docker compose`: |
| 59 | + |
| 60 | + docker compose kill --signal SIGUSR1 |
| 61 | + |
| 62 | +## Configuration Options for Minecraft Server Health Monitoring |
| 63 | + |
| 64 | +The image tags include specific variables to simplify configuration for monitoring the health of a Minecraft server: |
| 65 | + |
| 66 | +- `-e SERVER_HOST=localhost` : This variable sets the host address of the Minecraft server to be monitored. By default, it is set to `localhost`, but you can replace it with the actual hostname or IP address of your Minecraft server. |
| 67 | + |
| 68 | +- `-e SERVER_PORT=25565` : This variable sets the port number on which the Minecraft server is running. By default, Minecraft servers run on port 25565, but if your server is configured to use a different port, you should replace `25565` with the correct port number. This helps the monitoring system to accurately check the health status of the Minecraft server on the specified port. |
| 69 | + |
| 70 | +## OpenJ9 Specific Options |
| 71 | + |
| 72 | +The openj9 image tags include specific variables to simplify configuration: |
| 73 | + |
| 74 | +- `-e TUNE_VIRTUALIZED=TRUE` : enables the option to |
| 75 | + [optimize for virtualized environments](https://www.eclipse.org/openj9/docs/xtunevirtualized/) |
| 76 | +- `-e TUNE_NURSERY_SIZES=TRUE` : configures nursery sizes where the initial size is 50% |
| 77 | + of the `MAX_MEMORY` and the max size is 80%. |
| 78 | + |
| 79 | +## Enabling rolling logs |
| 80 | + |
| 81 | +By default the vanilla log file will grow without limit. The logger can be reconfigured to use a rolling log files strategy by using: |
| 82 | + |
| 83 | +``` |
| 84 | + -e ENABLE_ROLLING_LOGS=true |
| 85 | +``` |
| 86 | + |
| 87 | +> **NOTE** this will interfere with interactive/color consoles [as described in the section above](#interactive-and-color-console) |
| 88 | +
|
| 89 | +## Timezone Configuration |
| 90 | + |
| 91 | +You can configure the timezone to match yours by setting the `TZ` environment variable: |
| 92 | + |
| 93 | + -e TZ=Europe/London |
| 94 | + |
| 95 | +such as: |
| 96 | + |
| 97 | + docker run -d -it -e TZ=Europe/London -p 25565:25565 --name mc itzg/minecraft-server |
| 98 | + |
| 99 | +Or mounting `/etc/timezone` as readonly (not supported on Windows): |
| 100 | + |
| 101 | + -v /etc/timezone:/etc/timezone:ro |
| 102 | + |
| 103 | +such as: |
| 104 | + |
| 105 | + docker run -d -it -v /etc/timezone:/etc/timezone:ro -p 25565:25565 --name mc itzg/minecraft-server |
| 106 | + |
| 107 | +## HTTP Proxy |
| 108 | + |
| 109 | +You may configure the use of an HTTP/HTTPS proxy by passing the proxy's "host:port" via the environment variable `PROXY`. In [the example compose file](https://github.com/itzg/docker-minecraft-server/blob/master/examples/docker-compose-proxied.yml) it references a Squid proxy. The host and port can be separately passed via the environment variables `PROXY_HOST` and `PROXY_PORT`. A `|` delimited list of hosts to exclude from proxying can be passed via `PROXY_NON_PROXY_HOSTS`. |
| 110 | + |
| 111 | +## Using "noconsole" option |
| 112 | + |
| 113 | +Some older versions (pre-1.14) of Spigot required `--noconsole` to be passed when detaching stdin, which can be done by setting `-e CONSOLE=FALSE`. |
| 114 | + |
| 115 | +## Explicitly disable GUI |
| 116 | + |
| 117 | +Some older servers get confused and think that the GUI interface is enabled. You can explicitly |
| 118 | +disable that by passing `-e GUI=FALSE`. |
| 119 | + |
| 120 | +## Stop Duration |
| 121 | + |
| 122 | +When the container is signaled to stop, the Minecraft process wrapper will attempt to send a "stop" command via RCON or console and waits for the process to gracefully finish. By default, it waits 60 seconds, but that duration can be configured by setting the environment variable `STOP_DURATION` to the number of seconds. |
| 123 | + |
| 124 | +Be sure to also increase the shutdown timeout described [here for docker compose down](https://docs.docker.com/reference/cli/docker/compose/down/#options) and [here for docker stop](https://docs.docker.com/reference/cli/docker/container/stop/#options). |
| 125 | + |
| 126 | +## Setup only |
| 127 | + |
| 128 | +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`. |
| 129 | + |
| 130 | +## Enable Flare Flags |
| 131 | + |
| 132 | +To enable the JVM flags required to fully support the [Flare profiling suite](https://blog.airplane.gg/flare), set the following variable: |
| 133 | + |
| 134 | + -e USE_FLARE_FLAGS=true |
| 135 | + |
| 136 | +Flare is built-in to Pufferfish/Purpur, and is available in [plugin form](https://github.com/TECHNOVE/FlarePlugin) for other server types. |
| 137 | + |
| 138 | +## Enable support for optimized SIMD operations |
| 139 | + |
| 140 | +To enable support for optimized SIMD operations, the JVM flag can be set with the following variable: |
| 141 | + |
| 142 | + -e USE_SIMD_FLAGS=true |
| 143 | + |
| 144 | +SIMD optimized operations are supported by Pufferfish and Purpur. |
| 145 | + |
| 146 | +## Downloading extra configuration files |
| 147 | + |
| 148 | +You can download additional configuration files or other resources before the server starts by using the `DOWNLOAD_EXTRA_CONFIGS` environment variable. This is useful for downloading configs that you want to patch or modify during the startup process. |
| 149 | + |
| 150 | +The format uses a `<` separator between the destination path and the source URL: |
| 151 | + |
| 152 | +``` |
| 153 | +DOWNLOAD_EXTRA_CONFIGS=destination<source_url[,destination2<source_url2,...] |
| 154 | +``` |
| 155 | + |
| 156 | +For example, to download configuration files for plugins: |
| 157 | + |
| 158 | +```yaml |
| 159 | +environment: |
| 160 | + DOWNLOAD_EXTRA_CONFIGS: | |
| 161 | + plugins/WorldEdit<https://raw.githubusercontent.com/EngineHub/WorldEdit/refs/heads/version/7.3.x/worldedit-bukkit/src/main/resources/defaults/config.yml |
| 162 | + plugins/EssentialsX<https://raw.githubusercontent.com/EssentialsX/Essentials/refs/heads/2.x/Essentials/src/main/resources/config.yml |
| 163 | +``` |
| 164 | +
|
| 165 | +Or as a single line: |
| 166 | +
|
| 167 | +```yaml |
| 168 | +environment: |
| 169 | + DOWNLOAD_EXTRA_CONFIGS: "plugins/WorldEdit<https://example.com/worldedit.yml,config<https://example.com/another.yml" |
| 170 | +``` |
| 171 | +
|
| 172 | +The files will be downloaded to `/data/` relative paths, so `plugins/WorldEdit` will be saved as `/data/plugins/WorldEdit/config.yml`. |
| 173 | + |
| 174 | +!!! note |
| 175 | + The downloaded files can be further processed using [environment variable replacement](interpolating.md) or [patch definitions](interpolating.md#patching-existing-files) |
| 176 | + |
| 177 | +## Enable timestamps in init logs |
| 178 | + |
| 179 | +Before the container starts the Minecraft Server its output is prefixed with `[init]`, such as |
| 180 | + |
| 181 | +``` |
| 182 | +[init] Starting the Minecraft server... |
| 183 | +``` |
| 184 | +
|
| 185 | +To also include the timestamp with each log, set `LOG_TIMESTAMP` to "true". The log output will then look like: |
| 186 | +
|
| 187 | +``` |
| 188 | +[init] 2022-02-05 16:58:33+00:00 Starting the Minecraft server... |
| 189 | +``` |
0 commit comments