Skip to content

Minecraft (Java) Server in Docker on a Synology NAS

Added Docker Compose details03/05/2021
Updated to show which version of the image to download09/06/2021
Cleaned up the Environment Variables section and included some new JAVA optimisations24/11/2021

In this guide I am going to take you through the steps to get a Minecraft server up and running. This applies to both a Vanilla and modded server.

We will be using DSM6 and the latest version of Docker at the time of writing. The server I run is now open to anyone who want’s to play, its usually up and running most of the time. You can see its status in the widget on the left of this page 🙂

Downloading the Container

Open up Docker within DSM and navigate to the ‘Registry’ tab and search for ITZG in the keyword box.within the results right click and download the ‘ITZG|Minecraft-Server’, When it asks which version number to download select the one that you require.

Minecraft VersionTag to Select
v1.18xLatest or JAVA17
v1.16 and belowJAVA15
Search and Download

Setting up a Docker User for Minecraft and Obtaining the GID and UID

In previous versions of this guide we used your default admin account for each container, this is not very secure so please now follow the separate setup guide and then head back here.

Setting up the container

Now we have downloaded the container and got hold of our user IDs we can move onto the next stage, where we will configure the Docker container. First go back into Docker and click on the ‘Image’ tab, in the list of your containers select the ITZG minecraft server, and click on ‘Launch’

Time to start

You will be greeted with the initial setup screen, this is where you can start specifying some of your preferences.

As this is a Minecraft server it will likely use as much memory and CPU usage as you allow it, if you are running the server on a lower specification Synology machine you will probably want to set limits around the CPU priority and memory usage to ensure DSM is still usable when the server is running.

In this case I am leaving this as the defaults, you can always come back and tweak these settings later once the server is setup.

The initial setup screen

Next up we are going to setup some other parts, click on the ‘Advanced’ button.

Advanced Tab

On this first tab you can decide if you want to create a shortcut to the server on the DSM desktop and also if you want the server to start up automatically if you ever restart your Syno, this is useful if you don’t want to login to manually startup the server.

Advanced Settings


In the next tab we need to setup where we want the various Minecraft world files to reside, having these outside of the container will mean you can make backups of the entire server, great if someone decides to flood the map with Lava!

Personally, I setup folders for each of the  containers I am running in the default Docker directory as this keeps things nice and tidy.

We are going to mount a single directory for this container, the internal “/data” directory to the NAS “/docker/minecraft” seen the screenshot to see exactly how this is laid out.

Specify where you world files should reside


You do not need to adjust and settings in this tab.

Port Settings

By default docker will automatically assign external ports to your Docker container, however we will never know what they are until the container is launched and also they may change upon a reboot, so we will need to assign some specific ports.

In the case of this container Minecraft uses high value port number so it’s unlikely to clash with any other containers or ports already used by DSM. So we are just going to enter the same port numbers on the left hand column.

Local PortContainer PortType
Assign your ports

Environment Variables – GID , UID, Server Type and EULA

We are now going to set up the specific options for the server including what type of server you would like to run and even a specific version.

Each of the value below are added by clicking the ‘Add’ button at the top of the screen and then entering each of the values below

UIDUID you obtained earlier
GIDGID you obtained earlier
EULATRUEThis accepts the Minecraft EULA, without this the server will not run
TYPESPIGOTYou can change this as per the list below
VERSIONLATESTYou can change this to any a specific version if you want e.g 1.13
JVM_XX_OPTS-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:InitiatingHeapOccupancyPercent=15These variables are used to increase the performance of the server – Copy and paste this exactly
MAX_MEMORY2GAmend the number to the amount of memory you want to allocate to the server this will depend on your system

Server Types


You have now completed the hard part of the guide, click on OK and you will be taken back to an overall summary screen, this is just a summary of the settings you have entered, just do a quick sanity check to make sure they are correct. if you want to launch the server immediately check the box and click on finish.

Final summary page

Server startup time

The first time the server is launched it may take a few minutes to start as the files are downloaded and the world in generated, this time will depend on how fast your Synology performs, you can track the progress by going into the ‘Containers’ tab and clicking on details, and then either viewing the terminal or log tabs.

All other server settings can be configured using the standard Minecraft file, I won’t be covering that here as there are extensive other guides out there.

Docker Compose

You can use the below code saved as minecraft.yml to do the entire process above in one quick command via SSH.

version: "3.2"
    image: itzg/minecraft-server:latest
    container_name: minecraft
      - JVM_XX_OPTS=-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:InitiatingHeapOccupancyPercent=15
      - MEMORY=2G
      - LEVEL=world
      - PVP=true
      - DIFFICULTY=easy
      - ENABLE_RCON=true
      - RCON_PORT=25575
      - SERVER_PORT=25565
      - ENABLE_AUTOPAUSE=false
      - EULA=TRUE
      - /volume1/docker/minecraft:/data:rw
      - 25565:25565/tcp
      - 25575:25575/tcp
    restart: unless-stopped
sudo docker-compose -f /volume1/docker/minecraft.yml up -d

Throw me some bits or buy me a coffee?

If you have found my site useful please consider pinging me a tip as it helps cover the cost of running the site, you can even buy me a coffee 🙂

Buy Me A Coffee
  • Bitcoin
  • Ethereum
  • Tether
  • Cardano
  • Polkadot
  • Binance coin
  • Litecoin
  • Bitcoin cash
  • Dogecoin
  • Monero
  • Omisego
Scan to Donate Bitcoin to bc1qfq8ccs2yar7aa60fye8wdpanwtvpqzvrys4h6u

Donate Bitcoin to this address

Scan the QR code or copy the address below into your wallet to send some Bitcoin

Tag/Note:- Donations
Scan to Donate Ethereum to 0x7C5A441a6Dd520a796442DC6DeFeFE88d79D95f3

Donate Ethereum to this address

Scan the QR code or copy the address below into your wallet to send some Ethereum

Scan to Donate Tether to 0x7C5A441a6Dd520a796442DC6DeFeFE88d79D95f3

Donate Tether to this address

Scan the QR code or copy the address below into your wallet to send some Tether

Scan to Donate Cardano to addr1qysaldwdyqu9u8y9a0l5d35sqv202xr4768se8wevlexatepm76u6gpctcwgt6llgmrfqqc575v8ta50pjwajeljd6hsa6ggvv

Donate Cardano to this address

Scan the QR code or copy the address below into your wallet to send some Cardano

Scan to Donate Polkadot to 14R7Xr3587UKYsnnLhvBd7YfVgXkW9i3FU4kHP8DocsdLSha

Donate Polkadot to this address

Scan the QR code or copy the address below into your wallet to send some Polkadot

Scan to Donate Binance coin to bnb14ye5rju74u5ythneaum2rjvp8eqep6wq8flghx

Donate Binance coin to this address

Scan the QR code or copy the address below into your wallet to send some Binance coin

Scan to Donate Litecoin to LfNfer3aSqLx4p8KfbbkT96ArXLXLDPxoD

Donate Litecoin to this address

Scan the QR code or copy the address below into your wallet to send some Litecoin

Scan to Donate Bitcoin cash to qqz9pgaxdz4mtdxqxnlk7apqmsn6qzw9j5pn5jpvrc

Donate Bitcoin cash to this address

Scan the QR code or copy the address below into your wallet to send some Bitcoin cash

Scan to Donate Dogecoin to DCwbNzfYHx22MDSyEVLWgfjxziYHtcgwAM

Donate Dogecoin to this address

Scan the QR code or copy the address below into your wallet to send some Dogecoin

Scan to Donate Monero to 45qwFr42XiA8egC5z2HdSQ2FzzP9VR1MvD5Sicg4EhGvdvTutx9GsF6DeU8DHAsTZy2ShBERjCB5rdy8iQ9CFnFu9Z6Adgw

Donate Monero to this address

Scan the QR code or copy the address below into your wallet to send some Monero

Scan to Donate Omisego to 0x162fc7781D3C6c6f27197A3A92567b5DAF258f19

Donate Omisego to this address

Scan the QR code or copy the address below into your wallet to send some Omisego

Published inGamingMinecraft


  1. John John

    Thanks for this brilliant guide. I set it all up and worked perfectly as bedrock. Did this so my kids would have a super safe closed environment for them and their friends, all good.

    After months of stability suddenly we can’t access the “world” via the Mine craft app as the server is reported as out of date. In settings it should be latest but it’s failing to update with the message in the log file “ minecraft download page failed”.

    Any advice on how to sort this?


  2. Uwe Uwe


    Nice guide, especially the part with the restricted user policy. Can I use this methodology also when I set up other docker containers?


    • Dr_Frankenstein Dr_Frankenstein

      Hey, all the Linux server containers have the UID values, you often need to check the read me to see what the container requires or how it expects permissions to be set.

  3. Cody Morgan Cody Morgan


    I followed this guide and was able to startup a Minecraft server with no problems. I am now looking at trying to add Forge Mod so I can add Mods to my server but I am not sure what the steps are to install forge. I have downloaded the .jar file forge-1.17.1-37.0.126-installer.jar but am not sure how to install this on the server. Is this possible within the container I have created using your steps or do we have to create an entire new container with this forge package and if so are you able to provide the steps on how to do that?


    • Dr_Frankenstein Dr_Frankenstein

      Hey, you can change the server type with the ‘Type’ environment variable to CURSEFORGE.. I assume you can then put the mods in the MOD folder that is created in the folder you mapped.

      • Cody Morgan Cody Morgan

        Below is the log file after only changing the Type from VANILLA to CURSEFORGE if that helps.

        [init] Resolved version given LATEST into 1.17.1
        [init] Resolving type given CURSEFORGE
        [init] **********************************************************************
        [init] NOTE: Some mods and modpacks may require Java 8.
        [init] If so, use itzg/minecraft-server:java8
        [init] **********************************************************************
        [init] Looking for Feed-The-Beast / CurseForge server modpack.
        [init] ERROR: FTB_SERVER_MOD is required to be set

        • Dr_Frankenstein Dr_Frankenstein

          Try stopping the container deleting everything inside the /docker/minecraft folder and starting it up again.

          • Cody Morgan Cody Morgan

            I tried this and it wont create anything within the folder now. Log stops and gives the following error at the bottom of the log and then tries to restart again over and over giving the same error.

            ERROR: FTB_SERVER_MOD is required to be set

            It not installing the Forge mod for me. From what I can find online this needs to be installed and then the environment value can point to the mod. Is this true or are you saying this should just create and install everything and work, if that is the case then its not working like that.

          • Cody Morgan Cody Morgan

            I was actually able to get it working by changing the type from CURSEFORGE to FORGE. It downloaded and installed it all for me then. Thanks for your help.

  4. Lee Lee

    Thank you so much for this! Everything went swimmingly until I try and connect to it from inside Minecraft and it can’t find it…

    • Dr_Frankenstein Dr_Frankenstein

      Have you manually added the server as the built in automatic search never seems to find anything

      • Lee Lee

        I have yeah, tried with and without the port. It seems like it finds something, moves to “encrypting” and then says it can’t connect!

        • Dr_Frankenstein Dr_Frankenstein

          Are you using the Java version of minecraft or the Bedrock version?

          • Lee Lee

            Java, running on a Mac

          • Dr_Frankenstein Dr_Frankenstein

            When you add the server it should only need the IP of your NAS without the port number.. when you add it does it show up like this?
            Minecraft Server Page

          • Lee Lee

            I can’t connect to it at all now, so no it just says it failed to connect. I seem to be having bigger problems with the container; it’s crashing every 20 or so minutes so I think i might just kill the container and start the process again to see if it was something i did…

          • Dr_Frankenstein Dr_Frankenstein

            It should just show as below – double check the port settings you used

  5. Afterburn Afterburn

    Hi Dr Frankenstein,

    Thanks for the terrific guide. I had referred to the Docker repository also, but this is a lot more specific for the Synology deployment. I’m using a 216+II with 8Gb Ram and DSM 7.0.1-42218

    I stuffed up the directory settings in Advanced tab prior to running on the first attempt without your notes. I deleted and restarted. Running no problems so far. I intend to use the whilelist.json to admit my sons friends to the server. I’ll update the environment to reflect its use.

    I also tried LEVEL_TYPE=AMPLIFIED in environment but I haven’t got it going.

    I’ve tested on the LAN side OK, am now to test on the WAN side.


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.