mirror of
https://github.com/itzg/docker-minecraft-server
synced 2024-12-13 05:42:28 +00:00
379 lines
12 KiB
Markdown
379 lines
12 KiB
Markdown
|
|
[![Docker Pulls](https://img.shields.io/docker/pulls/itzg/minecraft-server.svg)](https://hub.docker.com/r/itzg/minecraft-server/)
|
|
|
|
|
|
This docker image provides a Minecraft Server that will automatically download the latest stable
|
|
version at startup. You can also run/upgrade to any specific version or the
|
|
latest snapshot. See the *Versions* section below for more information.
|
|
|
|
To simply use the latest stable version, run
|
|
|
|
docker run -d -p 25565:25565 --name mc itzg/minecraft-server
|
|
|
|
where the standard server port, 25565, will be exposed on your host machine.
|
|
|
|
If you want to serve up multiple Minecraft servers or just use an alternate port,
|
|
change the host-side port mapping such as
|
|
|
|
docker run -p 25566:25565 ...
|
|
|
|
will serve your Minecraft server on your host's port 25566 since the `-p` syntax is
|
|
`host-port`:`container-port`.
|
|
|
|
Speaking of multiple servers, it's handy to give your containers explicit names using `--name`, such as
|
|
|
|
docker run -d -p 25565:25565 --name mc itzg/minecraft-server
|
|
|
|
With that you can easily view the logs, stop, or re-start the container:
|
|
|
|
docker logs -f mc
|
|
( Ctrl-C to exit logs action )
|
|
|
|
docker stop mc
|
|
|
|
docker start mc
|
|
|
|
## Interacting with the server
|
|
|
|
In order to attach and interact with the Minecraft server, add `-it` when starting the container, such as
|
|
|
|
docker run -d -it -p 25565:25565 --name mc itzg/minecraft-server
|
|
|
|
With that you can attach and interact at any time using
|
|
|
|
docker attach mc
|
|
|
|
and then Control-p Control-q to **detach**.
|
|
|
|
For remote access, configure your Docker daemon to use a `tcp` socket (such as `-H tcp://0.0.0.0:2375`)
|
|
and attach from another machine:
|
|
|
|
docker -H $HOST:2375 attach mc
|
|
|
|
Unless you're on a home/private LAN, you should [enable TLS access](https://docs.docker.com/articles/https/).
|
|
|
|
## EULA Support
|
|
|
|
Mojang now requires accepting the [Minecraft EULA](https://account.mojang.com/documents/minecraft_eula). To accept add
|
|
|
|
-e EULA=TRUE
|
|
|
|
such as
|
|
|
|
docker run -d -it -e EULA=TRUE -p 25565:25565 --name mc itzg/minecraft-server
|
|
|
|
## Attaching data directory to host filesystem
|
|
|
|
In order to readily access the Minecraft data, use the `-v` argument
|
|
to map a directory on your host machine to the container's `/data` directory, such as:
|
|
|
|
docker run -d -v /path/on/host:/data ...
|
|
|
|
When attached in this way you can stop the server, edit the configuration under your attached `/path/on/host`
|
|
and start the server again with `docker start CONTAINERID` to pick up the new configuration.
|
|
|
|
**NOTE**: By default, the files in the attached directory will be owned by the host user with UID of 1000 and host group with GID of 1000.
|
|
You can use an different UID and GID by passing the options:
|
|
|
|
-e UID=1000 -e GID=1000
|
|
|
|
replacing 1000 with a UID and GID that is present on the host.
|
|
Here is one way to find the UID and GID:
|
|
|
|
id some_host_user
|
|
getent group some_host_group
|
|
|
|
## Versions
|
|
|
|
To use a different Minecraft version, pass the `VERSION` environment variable, which can have the value
|
|
|
|
* LATEST
|
|
* SNAPSHOT
|
|
* (or a specific version, such as "1.7.9")
|
|
|
|
For example, to use the latest snapshot:
|
|
|
|
docker run -d -e VERSION=SNAPSHOT ...
|
|
|
|
or a specific version:
|
|
|
|
docker run -d -e VERSION=1.7.9 ...
|
|
|
|
## Running a Forge Server
|
|
|
|
Enable Forge server mode by adding a `-e TYPE=FORGE` to your command-line.
|
|
By default the container will run the `RECOMMENDED` version of [Forge server](http://www.minecraftforge.net/wiki/)
|
|
but you can also choose to run a specific version with `-e FORGEVERSION=10.13.4.1448`.
|
|
|
|
$ docker run -d -v /path/on/host:/data -e VERSION=1.7.10 \
|
|
-e TYPE=FORGE -e FORGEVERSION=10.13.4.1448 \
|
|
-p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
|
|
|
|
In order to add mods, you have two options.
|
|
|
|
### Using the /data volume
|
|
|
|
This is the easiest way if you are using a persistent `/data` mount.
|
|
|
|
To do this, you will need to attach the container's `/data` directory
|
|
(see "Attaching data directory to host filesystem”).
|
|
Then, you can add mods to the `/path/on/host/mods` folder you chose. From the example above,
|
|
the `/path/on/host` folder contents look like:
|
|
|
|
```
|
|
/path/on/host
|
|
├── mods
|
|
│ └── ... INSTALL MODS HERE ...
|
|
├── config
|
|
│ └── ... CONFIGURE MODS HERE ...
|
|
├── ops.json
|
|
├── server.properties
|
|
├── whitelist.json
|
|
└── ...
|
|
```
|
|
|
|
If you add mods while the container is running, you'll need to restart it to pick those
|
|
up:
|
|
|
|
docker stop mc
|
|
docker start mc
|
|
|
|
### Using separate mounts
|
|
|
|
This is the easiest way if you are using an ephemeral `/data` filesystem,
|
|
or downloading a world with the `WORLD` option.
|
|
|
|
There are two additional volumes that can be mounted; `/mods` and `/config`.
|
|
Any files in either of these filesystems will be copied over to the main
|
|
`/data` filesystem before starting Minecraft.
|
|
|
|
This works well if you want to have a common set of modules in a separate
|
|
location, but still have multiple worlds with different server requirements
|
|
in either persistent volumes or a downloadable archive.
|
|
|
|
## Running a Bukkit/Spigot server
|
|
|
|
Enable Bukkit/Spigot server mode by adding a `-e TYPE=BUKKIT -e VERSION=1.8` or `-e TYPE=SPIGOT -e VERSION=1.8` to your command-line.
|
|
|
|
The VERSION option should be set to 1.8, as this is the only version of CraftBukkit and Spigot currently
|
|
available. The latest build in this branch will be used.
|
|
|
|
$ docker run -d -v /path/on/host:/data \
|
|
-e TYPE=SPIGOT -e VERSION=1.8 \
|
|
-p 25565:25565 -e EULA=TRUE --name mc itzg/minecraft-server
|
|
|
|
You can install Bukkit plugins in two ways.
|
|
|
|
### Using the /data volume
|
|
|
|
This is the easiest way if you are using a persistent `/data` mount.
|
|
|
|
To do this, you will need to attach the container's `/data` directory
|
|
(see "Attaching data directory to host filesystem”).
|
|
Then, you can add plugins to the `/path/on/host/plugins` folder you chose. From the example above,
|
|
the `/path/on/host` folder contents look like:
|
|
|
|
```
|
|
/path/on/host
|
|
├── plugins
|
|
│ └── ... INSTALL PLUGINS HERE ...
|
|
├── ops.json
|
|
├── server.properties
|
|
├── whitelist.json
|
|
└── ...
|
|
```
|
|
|
|
If you add plugins while the container is running, you'll need to restart it to pick those
|
|
up:
|
|
|
|
docker stop mc
|
|
docker start mc
|
|
|
|
### Using separate mounts
|
|
|
|
This is the easiest way if you are using an ephemeral `/data` filesystem,
|
|
or downloading a world with the `WORLD` option.
|
|
|
|
There is one additional volume that can be mounted; `/plugins`.
|
|
Any files in this filesystem will be copied over to the main
|
|
`/data/plugins` filesystem before starting Minecraft.
|
|
|
|
This works well if you want to have a common set of plugins in a separate
|
|
location, but still have multiple worlds with different server requirements
|
|
in either persistent volumes or a downloadable archive.
|
|
|
|
## Using Docker Compose
|
|
|
|
Rather than type the server options below, the port mappings above, etc
|
|
every time you want to create new Minecraft server, you can now use
|
|
[Docker Compose](https://docs.docker.com/compose/). Start with a
|
|
`docker-compose.yml` file like the following:
|
|
|
|
```
|
|
minecraft-server:
|
|
ports:
|
|
- "25565:25565"
|
|
|
|
environment:
|
|
EULA: TRUE
|
|
|
|
image: itzg/minecraft-server
|
|
|
|
container_name: mc
|
|
|
|
tty: true
|
|
stdin_open: true
|
|
restart: always
|
|
```
|
|
|
|
and in the same directory as that file run
|
|
|
|
docker-compose -d up
|
|
|
|
Now, go play...or adjust the `environment` section to configure
|
|
this server instance.
|
|
|
|
## Server configuration
|
|
|
|
### Difficulty
|
|
|
|
The difficulty level (default: `easy`) can be set like:
|
|
|
|
docker run -d -e DIFFICULTY=hard ...
|
|
|
|
Valid values are: `peaceful`, `easy`, `normal`, and `hard`, and an
|
|
error message will be output in the logs if it's not one of these
|
|
values.
|
|
|
|
### Whitelist Players
|
|
|
|
To whitelist players for your Minecraft server, pass the Minecraft usernames separated by commas via the `WHITELIST` environment variable, such as
|
|
|
|
docker run -d -e WHITELIST=user1,user2 ...
|
|
|
|
If the `WHITELIST` environment variable is not used, any user can join your Minecraft server if it's publicly accessible.
|
|
|
|
### Op/Administrator Players
|
|
|
|
To add more "op" (aka adminstrator) users to your Minecraft server, pass the Minecraft usernames separated by commas via the `OPS` environment variable, such as
|
|
|
|
docker run -d -e OPS=user1,user2 ...
|
|
|
|
### Server icon
|
|
|
|
A server icon can be configured using the `ICON` variable. The image will be automatically
|
|
downloaded, scaled, and converted from any other image format:
|
|
|
|
docker run -d -e ICON=http://..../some/image.png ...
|
|
|
|
### Level Seed
|
|
|
|
If you want to create the Minecraft level with a specific seed, use `SEED`, such as
|
|
|
|
docker run -d -e SEED=1785852800490497919 ...
|
|
|
|
### Game Mode
|
|
|
|
By default, Minecraft servers are configured to run in Survival mode. You can
|
|
change the mode using `MODE` where you can either provide the [standard
|
|
numerical values](http://minecraft.gamepedia.com/Game_mode#Game_modes) or the
|
|
shortcut values:
|
|
|
|
* creative
|
|
* survival
|
|
* adventure
|
|
* spectator (only for Minecraft 1.8 or later)
|
|
|
|
For example:
|
|
|
|
docker run -d -e MODE=creative ...
|
|
|
|
### Message of the Day
|
|
|
|
The message of the day, shown below each server entry in the UI, can be changed with the `MOTD` environment variable, such as
|
|
|
|
docker run -d -e 'MOTD=My Server' ...
|
|
|
|
If you leave it off, the last used or default message will be used. _The example shows how to specify a server
|
|
message of the day that contains spaces by putting quotes around the whole thing._
|
|
|
|
### PVP Mode
|
|
|
|
By default, servers are created with player-vs-player (PVP) mode enabled. You can disable this with the `PVP`
|
|
environment variable set to `false`, such as
|
|
|
|
docker run -d -e PVP=false ...
|
|
|
|
### Level Type and Generator Settings
|
|
|
|
By default, a standard world is generated with hills, valleys, water, etc. A different level type can
|
|
be configured by setting `LEVEL_TYPE` to
|
|
|
|
* DEFAULT
|
|
* FLAT
|
|
* LARGEBIOMES
|
|
* AMPLIFIED
|
|
* CUSTOMIZED
|
|
|
|
Descriptions are available at the [gamepedia](http://minecraft.gamepedia.com/Server.properties).
|
|
|
|
When using a level type of `FLAT` and `CUSTOMIZED`, you can further configure the world generator
|
|
by passing [custom generator settings](http://minecraft.gamepedia.com/Superflat).
|
|
**Since generator settings usually have ;'s in them, surround the -e value with a single quote, like below.**
|
|
|
|
For example (just the `-e` bits):
|
|
|
|
-e LEVEL_TYPE=flat -e 'GENERATOR_SETTINGS=3;minecraft:bedrock,3*minecraft:stone,52*minecraft:sandstone;2;'
|
|
|
|
### World Save Name
|
|
|
|
You can either switch between world saves or run multiple containers with different saves by using the `LEVEL` option,
|
|
where the default is "world":
|
|
|
|
docker run -d -e LEVEL=bonus ...
|
|
|
|
**NOTE:** if running multiple containers be sure to either specify a different `-v` host directory for each
|
|
`LEVEL` in use or don't use `-v` and the container's filesystem will keep things encapsulated.
|
|
|
|
### Downloadable world
|
|
|
|
Instead of mounting the `/data` volume, you can instead specify the URL of
|
|
a ZIP file containing an archived world. This will be downloaded, and
|
|
unpacked in the `/data` directory; if it does not contain a subdirectory
|
|
called `world/` then it will be searched for a file `level.dat` and the
|
|
containing subdirectory renamed to `world`. This means that most of the
|
|
archived Minecraft worlds downloadable from the Internet will already be in
|
|
the correct format.
|
|
|
|
The ZIP file may also contain a `server.properties` file and `modules`
|
|
directory, if required.
|
|
|
|
docker run -d -e WORLD=http://www.example.com/worlds/MySave.zip ...
|
|
|
|
**NOTE:** Unless you also mount `/data` as an external volume, this world
|
|
will be deleted when the container is deleted.
|
|
|
|
**NOTE:** This URL must be accessible from inside the container. Therefore,
|
|
you should use an IP address or a globally resolveable FQDN, or else the
|
|
name of a linked container.
|
|
|
|
### Downloadable mod/plugin pack for Forge, Bukkit, and Spigot Servers
|
|
|
|
Like the `WORLD` option above, you can specify the URL of a "mod pack"
|
|
to download and install into `mods` for Forge or `plugins` for Bukkit/Spigot.
|
|
To use this option pass the environment variable `MODPACK`, such as
|
|
|
|
docker run -d -e MODPACK=http://www.example.com/mods/modpack.zip ...
|
|
|
|
**NOTE:** The referenced URL must be a zip file with one or more jar files at the
|
|
top level of the zip archive. Make sure the jars are compatible with the
|
|
particular `TYPE` of server you are running.
|
|
|
|
## JVM Configuration
|
|
|
|
### Memory Limit
|
|
|
|
The Java memory limit can be adjusted using the `JVM_OPTS` environment variable, where the default is
|
|
the setting shown in the example (max and min at 1024 MB):
|
|
|
|
docker run -e 'JVM_OPTS=-Xmx1024M -Xms1024M' ...
|