Skip to content

Commit 99f31d5

Browse files
itzgEmilyxFox
itzg
and
EmilyxFox
authored
Restore conditional logic for MeowIce flags (#3647)
Co-authored-by: EmilyxFox <48589793+EmilyxFox@users.noreply.github.com>
1 parent 155b478 commit 99f31d5

File tree

2 files changed

+144
-145
lines changed

2 files changed

+144
-145
lines changed

‎docs/configuration/jvm-options.md‎

Lines changed: 139 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -1,143 +1,139 @@
1-
# JVM Options
2-
3-
## Memory Limit
4-
5-
By default, the image declares an initial and maximum Java memory-heap limit of 1 GB. There are several ways to adjust the memory settings:
6-
7-
- `MEMORY`: "1G" by default, can be used to adjust both initial (`Xms`) and max (`Xmx`) memory heap settings of the JVM
8-
- `INIT_MEMORY`: independently sets the initial heap size
9-
- `MAX_MEMORY`: independently sets the max heap size
10-
11-
The values of all three are passed directly to the JVM and support format/units as `<size>[g|G|m|M|k|K]`.
12-
13-
!!! example "Using docker run"
14-
15-
```
16-
-e MEMORY=2G
17-
```
18-
19-
or to use init and max memory:
20-
21-
```
22-
-e INIT_MEMORY=1G -e MAX_MEMORY=4G
23-
```
24-
25-
!!! example "Using compose file"
26-
27-
```
28-
environment:
29-
MEMORY: 2G
30-
```
31-
32-
or to use init and max memory:
33-
34-
```
35-
environment:
36-
INIT_MEMORY: 1G
37-
MAX_MEMORY: 4G
38-
```
39-
40-
To let the JVM calculate the heap size from the container declared memory limit, unset `MEMORY` with an empty value, such as `-e MEMORY=""`. By default, the JVM will use 25% of the container memory limit as the heap limit; however, as an example the following would tell the JVM to use 75% of the container limit of 4GB of memory:
41-
42-
!!! example "MaxRAMPercentage using compose file"
43-
44-
```
45-
environment:
46-
MEMORY: ""
47-
JVM_XX_OPTS: "-XX:MaxRAMPercentage=75"
48-
deploy:
49-
resources:
50-
limits:
51-
memory: 4G
52-
```
53-
54-
!!! important
55-
The settings above only set the Java **heap** limits. Memory resource requests and limits on the overall container should also account for non-heap memory usage. An extra 25% is [a general best practice](https://dzone.com/articles/best-practices-java-memory-arguments-for-container).
56-
57-
## Extra JVM Options
58-
59-
General JVM options can be passed to the Minecraft Server invocation by passing a `JVM_OPTS`
60-
environment variable. The JVM requires `-XX` options to precede `-X` options, so those can be declared in `JVM_XX_OPTS`. Both variables are space-delimited, raw JVM arguments.
61-
62-
```
63-
docker run ... -e JVM_OPTS="-someJVMOption someJVMOptionValue" ...
64-
```
65-
66-
**NOTE** When declaring `JVM_OPTS` in a compose file's `environment` section with list syntax, **do not** include the quotes:
67-
68-
```yaml
69-
environment:
70-
- EULA=true
71-
- JVM_OPTS=-someJVMOption someJVMOptionValue
72-
```
73-
74-
Using object syntax is recommended and more intuitive:
75-
76-
```yaml
77-
environment:
78-
EULA: "true"
79-
JVM_OPTS: "-someJVMOption someJVMOptionValue"
80-
# or
81-
# JVM_OPTS: -someJVMOption someJVMOptionValue
82-
```
83-
84-
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.)
85-
86-
For example, instead of passing
87-
88-
```yaml
89-
JVM_OPTS: -Dfml.queryResult=confirm -Dname=value
90-
```
91-
92-
you can use
93-
94-
```yaml
95-
JVM_DD_OPTS: fml.queryResult=confirm,name=value
96-
```
97-
98-
## Enable Remote JMX for Profiling
99-
100-
To enable remote JMX, such as for profiling with VisualVM or JMC, set the environment variable `ENABLE_JMX` to "true", set `JMX_HOST` to the IP/host running the Docker container, and add a port forwarding of TCP port 7091, such as:
101-
102-
!!! example
103-
104-
With `docker run`
105-
106-
```
107-
-e ENABLE_JMX=true -e JMX_HOST=$HOSTNAME -p 7091:7091
108-
```
109-
110-
If needing to map to a different port, then also set the environment variable `JMX_PORT` to the desired host port.
111-
112-
!!! example
113-
114-
With a compose file:
115-
116-
```yaml
117-
environment:
118-
ENABLE_JMX: true
119-
JMX_HOST: ${HOSTNAME}
120-
JMX_PORT: "7092"
121-
ports:
122-
- "7092:7092"
123-
```
124-
125-
## Enable Aikar's Flags
126-
127-
[Aikar has done some research](https://aikar.co/2018/07/02/tuning-the-jvm-g1gc-garbage-collector-flags-for-minecraft/) into finding the optimal JVM flags for GC tuning, which becomes more important as more users are connected concurrently. [PaperMC also has an explanation](https://docs.papermc.io/paper/aikars-flags) of what the JVM flags are doing.
128-
129-
The set of flags documented there can be added using
130-
131-
-e USE_AIKAR_FLAGS=true
132-
133-
When `MEMORY` is greater than or equal to 12G, then the Aikar flags will be adjusted according to the article.
134-
135-
## Enable MeowIce's Flags
136-
137-
[MeowIce has created an updated set of JVM flags](https://github.com/MeowIce/meowice-flags?tab=readme-ov-file#why-would-i-have-to-switch-) based on Aikar's flags but with support for optimizations for Java 17 and above
138-
139-
The set of flags documented there can be added using
140-
141-
-e USE_MEOWICE_FLAGS=true
142-
143-
There is an optional `USE_MEOWICE_GRAALVM_FLAGS` variable to enable GraalVM specific optimizations, defaults to `TRUE` if USE_MEOWICE_GRAALVM_FLAGS is `TRUE`
1+
# JVM Options
2+
3+
## Memory Limit
4+
5+
By default, the image declares an initial and maximum Java memory-heap limit of 1 GB. There are several ways to adjust the memory settings:
6+
7+
- `MEMORY`: "1G" by default, can be used to adjust both initial (`Xms`) and max (`Xmx`) memory heap settings of the JVM
8+
- `INIT_MEMORY`: independently sets the initial heap size
9+
- `MAX_MEMORY`: independently sets the max heap size
10+
11+
The values of all three are passed directly to the JVM and support format/units as `<size>[g|G|m|M|k|K]`.
12+
13+
!!! example "Using docker run"
14+
15+
```
16+
-e MEMORY=2G
17+
```
18+
19+
or to use init and max memory:
20+
21+
```
22+
-e INIT_MEMORY=1G -e MAX_MEMORY=4G
23+
```
24+
25+
!!! example "Using compose file"
26+
27+
```
28+
environment:
29+
MEMORY: 2G
30+
```
31+
32+
or to use init and max memory:
33+
34+
```
35+
environment:
36+
INIT_MEMORY: 1G
37+
MAX_MEMORY: 4G
38+
```
39+
40+
To let the JVM calculate the heap size from the container declared memory limit, unset `MEMORY` with an empty value, such as `-e MEMORY=""`. By default, the JVM will use 25% of the container memory limit as the heap limit; however, as an example the following would tell the JVM to use 75% of the container limit of 4GB of memory:
41+
42+
!!! example "MaxRAMPercentage using compose file"
43+
44+
```
45+
environment:
46+
MEMORY: ""
47+
JVM_XX_OPTS: "-XX:MaxRAMPercentage=75"
48+
deploy:
49+
resources:
50+
limits:
51+
memory: 4G
52+
```
53+
54+
!!! important
55+
The settings above only set the Java **heap** limits. Memory resource requests and limits on the overall container should also account for non-heap memory usage. An extra 25% is [a general best practice](https://dzone.com/articles/best-practices-java-memory-arguments-for-container).
56+
57+
## Extra JVM Options
58+
59+
General JVM options can be passed to the Minecraft Server invocation by passing a `JVM_OPTS`
60+
environment variable. The JVM requires `-XX` options to precede `-X` options, so those can be declared in `JVM_XX_OPTS`. Both variables are space-delimited, raw JVM arguments.
61+
62+
```
63+
docker run ... -e JVM_OPTS="-someJVMOption someJVMOptionValue" ...
64+
```
65+
66+
**NOTE** When declaring `JVM_OPTS` in a compose file's `environment` section with list syntax, **do not** include the quotes:
67+
68+
```yaml
69+
environment:
70+
- EULA=true
71+
- JVM_OPTS=-someJVMOption someJVMOptionValue
72+
```
73+
74+
Using object syntax is recommended and more intuitive:
75+
76+
```yaml
77+
environment:
78+
EULA: "true"
79+
JVM_OPTS: "-someJVMOption someJVMOptionValue"
80+
# or
81+
# JVM_OPTS: -someJVMOption someJVMOptionValue
82+
```
83+
84+
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.)
85+
86+
For example, instead of passing
87+
88+
```yaml
89+
JVM_OPTS: -Dfml.queryResult=confirm -Dname=value
90+
```
91+
92+
you can use
93+
94+
```yaml
95+
JVM_DD_OPTS: fml.queryResult=confirm,name=value
96+
```
97+
98+
## Enable Remote JMX for Profiling
99+
100+
To enable remote JMX, such as for profiling with VisualVM or JMC, set the environment variable `ENABLE_JMX` to "true", set `JMX_HOST` to the IP/host running the Docker container, and add a port forwarding of TCP port 7091, such as:
101+
102+
!!! example
103+
104+
With `docker run`
105+
106+
```
107+
-e ENABLE_JMX=true -e JMX_HOST=$HOSTNAME -p 7091:7091
108+
```
109+
110+
If needing to map to a different port, then also set the environment variable `JMX_PORT` to the desired host port.
111+
112+
!!! example
113+
114+
With a compose file:
115+
116+
```yaml
117+
environment:
118+
ENABLE_JMX: true
119+
JMX_HOST: ${HOSTNAME}
120+
JMX_PORT: "7092"
121+
ports:
122+
- "7092:7092"
123+
```
124+
125+
## Enable Aikar's Flags
126+
127+
[Aikar has done some research](https://aikar.co/2018/07/02/tuning-the-jvm-g1gc-garbage-collector-flags-for-minecraft/) into finding the optimal JVM flags for GC tuning, which becomes more important as more users are connected concurrently. [PaperMC also has an explanation](https://docs.papermc.io/paper/aikars-flags) of what the JVM flags are doing.
128+
129+
The set of flags documented there can be added using
130+
131+
-e USE_AIKAR_FLAGS=true
132+
133+
When `MEMORY` is greater than or equal to 12G, then the Aikar flags will be adjusted according to the article.
134+
135+
## Enable MeowIce's Flags
136+
137+
[MeowIce has created an updated set of JVM flags](https://github.com/MeowIce/meowice-flags?tab=readme-ov-file#why-would-i-have-to-switch-) based on Aikar's flags but with support for optimizations for Java 17 and above
138+
139+
The set of flags documented there can be added by setting the environment variable `USE_MEOWICE_FLAGS` to `true`. There is an optional `USE_MEOWICE_GRAALVM_FLAGS` variable to enable GraalVM specific optimizations, defaults to `FALSE`.

‎scripts/start-finalExec‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -151,16 +151,19 @@ if isTrue "${ENABLE_JMX}"; then
151151
log "JMX is enabled. Make sure you have port forwarding for ${JMX_PORT}"
152152
fi
153153

154+
: "${USE_AIKAR_FLAGS:=false}"
155+
: "${USE_MEOWICE_FLAGS:=false}"
156+
: "${USE_MEOWICE_GRAALVM_FLAGS:=false}"
157+
154158
if isTrue "${USE_MEOWICE_FLAGS}"; then
155159
java_major_version=$(mc-image-helper java-release)
156160
if [[ $java_major_version -gt 16 ]]; then
157-
USE_MEOWICE_GRAALVM_FLAGS="${USE_MEOWICE_GRAALVM_FLAGS:-TRUE}"
158161
log "Java version $java_major_version using MeowIce's flags for Java 17+"
159162
else
160163
log "Your Java version is $java_major_version, MeowIce's flags are for Java 17+ falling back to Aikar's"
161164
USE_MEOWICE_FLAGS=FALSE
165+
USE_AIKAR_FLAGS=TRUE
162166
fi
163-
USE_AIKAR_FLAGS=TRUE
164167
fi
165168

166169
if isTrue "${USE_AIKAR_FLAGS}"; then

0 commit comments

Comments
 (0)