Skip to content

Minecraft (Java) Server in Docker on a Synology NAS (Including Mods)

Added Docker Compose details03/05/2021

This guide replaces the two previous guides on the site, they will be archived in due course.

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 ‘Latest’

Search and Download
Select the version

Setting up a Docker User for Minecraft and Obtaining the PGID and PUID

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.

Assign your ports

Environment Variables – PGID , PUID, 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.

*Please note that you must not change the UID and GID options in the first red box.

First up Click on the + sign at the top of the options page, in the ‘Variable’ box type PGID and enter the value you obtained earlier, repeat this step for the PUID. (See screenshot)

In addition to this we have to accept the Minecraft EULA so you will add an additional variable called EULA with the value set to TRUE.

You can now specify the type of server you would like to run by amending the value next to the TYPE variable.


If you want to run a specific version of the server you can amend the VERSION variable from LATEST to for example 1.13

*Please note the screenshot below has been updated, as you can see after you run the server for the first time a lot of additional variables are automatically added. Ignore the GID and UID towards the top of this screenshot we only need to fill in the items at the bottom!

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
      - 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 --remove-orphans
Published inGamingMinecraft


  1. Wayne Wayne

    the artcle is called, “Minecraft (Java) Server in Docker on a Synology NAS (Including Mods)” I dont see any advise on the mods…

    • Dr_Frankenstein Dr_Frankenstein

      You should be able to drop them in to the appropriate folder. Including plugins. I have a few plugins running on my own server.

      • Wayne Wayne

        Would you mind being more specific please? Which folders for plugins and which for mods, also which client do you use to connect to the server?

  2. Daniel Daniel

    I followed this method, but I’m unable to get the server to start. The error message I get in the log is “curl: (6) Could not resolve host:”

    From googling around, I’m aware this may be due to DNS settings. But I cannot find any reliable source of information to resolve the issue.

    • Wayne Wayne

      Set the server to offline mode and try that, it should reuire external DNS if its local.
      Go to Docker folder on your NAS and open “” and and make “online-mode=false”

      • Daniel Daniel

        Just restarting repeatedly generating the same error. I’ve double checked the firewalls and port forwarding settings. DNS set to auto in the router. So I have no clue what else to do.

        • Dr_Frankenstein Dr_Frankenstein

          Have you tried running the container in network host mode… Set it up again and on the Network tab tick the ‘Use the same network as Docker Host’

          • Daniel Daniel

            Thanks, that worked. Almost there. Server is up and running now, but I’m unable to discover it from Minecraft on an iPad connected to the same network. Tried to add it both with local and external IP addresses, and ensured that port 25565 is still forwarded, but not able to ping the server.

          • Dr_Frankenstein Dr_Frankenstein

            The ipad is using the bedrock version not Java. You will have to use a Bedrock server container instead.

    • Patrick Patrick

      I have the same problem “Could not resolve host.” I have Synology DSN Server installed and it seems it may have to do with that, although I am not clear what the problem is.

      There are various answers online where –dns was added to command line invocation of Docker. However, I haven’t found out how I could fix this through the Synology GUI, such as if an equivalent fix would be possible through an environmental variable.

  3. Tim Tim

    I have the forge server running on the NAS and can connect to it directly using my internal IP but I am not sure what the NAS’ external IP is because the external IP I was using from my PC isn’t finding the server anymore. Any ideas on how to either find the NAS’ external IP (if it is in fact somehow different than the one I was using from my PC) or on what the problem is?

    My first thought was port forwarding but that’s already functioning since I was just running the server from this router last night..

    • Tim Tim

      Addendum, I realized maybe the problem was that the server didn’t have a static IP so I fixed that but still no avail. Now when I try to join the server it just more quickly says “cant connect to server”

      • Tim Tim

        And final addendum, I got minecraft to recognize the server through some fiddling with NAS port forwarding and settings (yay!) but it says it is an outdated server so will just try to see what’s going on there but seems like I got it mostly fixed! I’ll keep these up here for others to see.

    • Tim Tim

      OKAY so final step, but actual problem identified: server is successfuly recognized, I can click to join but when I do I get this error message:

      “Authentication servers are down. Please try again later. Sorry!”

      Is that a problem with my docker settings or something out of my control?

      • Dr_Frankenstein Dr_Frankenstein

        Sounds like it’s the auth servers?

        • Tim Tim

          That’s what I thought but I’m able to join other public servers, like Hypixel, so I think it’s something with my docker server? I can also join the server if it’s hosted on my PC :/

          I just don’t know what setting in the properties could be causing the server to be viewable, joinable, but not authenticatable

  4. Thomas Thomas

    Im using your docker on my DS218+. It works great.
    Does the autosave modus work on the DS218+ too?
    I set the max-tick-time parameter to -1.
    The java goes to pause ” [Autopause] Pausing Java process” after the AUTOPAUSE_TIMEOUT_INIT = 60 i set but it never gets knocked and java does not resume.
    I set AUTOPAUSE_KNOCK_INTERFACE = eth0. That is the bridged one i think.
    Is it a problem with the user rights or the server version. I use the latest version of the container with a vanilla server.

    • Dr_Frankenstein Dr_Frankenstein

      Hey, this is something you will need to ask the actual Docker container owner

      • Thomas Thomas

        I found it.
        When i start the docker container as admin the java process resumed after kocking with the minecraft client.
        So the docker user wich i used for the container has not enough rights to listen to the eth0.

  5. Christina Christina

    I used your Guide and made my own Minecraft Server on my Synology NAS. Everything works perfectly. The only Problem: When I copy my Save-File from an already existing Server (ScalaCube), it won’t load that world. I edited the, but it still won’t open that world.
    It was originally a SinglePlayer World which I copied to the ScalaCube Server – that worked without Problems. And when I copy the Server-Save to my local .minecraft/saves Folder, the world is the same as on the ScalaCube Server.
    I have no Idea, what I could have done wrong – it should be as easy as copying the save-folder onto the Synology (of course in the correct Folder) and editing the, but it won’t work!!!!!
    Please help, I’m really close to losing it -.-

    • Christina Christina

      OK, I solved the Problem. I feel so stupid.
      I didn’t check my World folder and missed, that it didn’t extract the .zip File correctly. It created another Folder in my World folder where the Files went.
      Because of it, the Server couldn’t find the save File and created a new world in the first World file.

      • Dr_Frankenstein Dr_Frankenstein

        Glad you fixed it

  6. nixforme12 nixforme12

    Does anyone know where I need to add the mods on the synology? Which path? I am trying to transfer all the mods from my sons computer to the NAS.

    • Dr_Frankenstein Dr_Frankenstein

      They go in a folder called /mods or /plugins which should be in the same folder as the main spigot_server.jar file

      • Wayne Wayne

        I dont seem to get the Mods to launch, tried both /mods and /plugins and no joy. Im using the TE_minecraft launcher if that matters. Game runs fin just no mods

  7. ngkrich ngkrich

    It seems this no longer works on Synology Docker. I was trying to troubleshoot it with the creator of the docker repo, but neither of us could get it working. End up with the following every time. Even when simplifying the config or downloading and running from SSH rather than the GUI.

    date stream content
    2021-02-03 19:16:28 stdout [init] ERROR: /data doesn’t seem to be writable. Please make sure attached directory is writable by uid=
    2021-02-03 19:16:28 stdout /start-configuration: line 28: id: command not found
    2021-02-03 19:16:28 stdout /start-configuration: line 27: touch: command not found
    2021-02-03 19:16:28 stdout [init] Running as uid= gid= with /data as ”
    2021-02-03 19:16:28 stdout /start-configuration: line 25: ls: command not found
    2021-02-03 19:16:28 stdout /start-configuration: line 25: id: command not found
    2021-02-03 19:16:28 stdout /start-configuration: line 25: id: command not found
    2021-02-03 19:16:28 stdout /start: line 8: [: =: unary operator expected
    2021-02-03 19:16:28 stdout /start: line 8: id: command not found
    2021-02-03 19:16:28 stdout /start: line 6: chmod: command not found

    • francois adams francois adams

      Maybe you should specify a real directory for /data and not just a share (for example if your shared directory in Syno is /temp, specify /temp/dir for the path)

    • Dr_Frankenstein Dr_Frankenstein

      This definitely still works I have it running on my Synology both via the built in GUI and via docker compose.

  8. Cyberiad Cyberiad


    Great tutorial and really easy to follow. I’m in the process of migrating from my PC to the NAS (like CERBERUS above). I’ve copied everything across, and it’s working, but I was wondering about an aspect of the config. I’ve been using the following batch file to run the server on my PC (using Aikar’s recommended settings):

    c:\MCServer\jdk-11.0.2\bin\java.exe -Xms10G -Xmx10G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -Dusing.aikars.flags= -jar paper-1.16.5-443.jar nogui

    I can see where I can modify the memory used (the MEMORY environment variable), but I’m not sure about the rest – can I add them in to the JVM_XX_OPTS variable? If so, how? Should they just be space-delimited? Any I shouldn’t add?

    • Cyberiad Cyberiad

      Looks like it was ok to just add them in to the JVM_XX_OPTS variable space-delimited. I only added the -XX ones, and not these;

  9. Bob Bob

    How do you make someone an admin?

    • Dr_Frankenstein Dr_Frankenstein

      You just need to open up the docker container in the DSM interface.. go to the Terminal tab and you can type in the commands you would normally do in a standard Minecraft server terminal.

    • Dr_Frankenstein Dr_Frankenstein

      You do this within the syno docker GUI in the terminal tab.

  10. Michael Michael

    I currently believe that defining different users is a waste of time as long as the containers are created with the web GUI.
    Did you check if defining PUID and PGID has any effect at all?

    We share the same urge to get our setups as secure as possible.
    So I tried to implement the solution you propose but I failed.

    I am using — DSM 6.2.3-25426 Update 3 — on my — DS216+II — to host mongodb and here it seems like mounting folders inside the docker directory can be done regardless of any permissions.
    I used this tutorial here but unfortunately Mr. Abt does not provide a screenshot :
    As if docker runs on root permissions anyway as long as a container is launched from the web GUI.
    While mounting any folder or shared folder outside the docker folder never worked, no matter what User:Group combination or environment variables I used, I could use any environment variable I want as long as the mount happens inside the docker shared folder.

    I also have a python script run by chron to execute a batch job that converts pdf into pdf/a with OCR Layer for a paperless home.
    When using this way the permissions actually control access.
    Persumably because the docker run command is not executed by sudo.

    I tested both 5 mins ago and I cannot find any other explanation.
    Maybe you have a better idea on what I am doing wrong.
    Your help would be appreciated very much :).

    • Dr_Frankenstein Dr_Frankenstein

      I think it depends on the container

      All the Linux|Server containers respect your PUID and GUID settings as when given incorrect permissions that are not granted for a share or folder the container does not have any access to it, so in my personal case if I tried to pass my /photo directory to Radarr it will just be empty as the user I have setup for my automation does not have access to it.

      However other containers without explicit access permissions have the permissions of the user setting them up (usually the admin) so will just allow access to any folders passed through that the admin has access to. (this is what the mongoDB one is doing).

      When you tick the box in the interface called ‘Enable high privilege’ you are granting root access for the container.

      I have pretty much moved exclusively to using Docker-Compose at this point it works the same way though permissions wise.

      So if you wanted to restrict your MongoDB setup you would create a user for it and run the container via the webui logged in with that user… or use docker-compose while logged in via SSH under that user. (obviously that user would be setup with explicit access to only the shares or folders you want the DB to have access to)

      Does that make sense. (I am learning this all as I go, but that is my understanding)

      • Michael Michael

        I found something that might also be helpful here:
        Seems like the mongo container really likes Owners permissions, I am wrong and your security can still be used.
        Probably not for mongodb, though.
        Thank god and user Szmeby for this insight :D.

  11. francois adams francois adams

    Copy the directory containing the world from your pc to the /data mount on docker, ensure the name of the directrory is the same in and launch the docker server, it should work.


    Is there a way to migrate pre-existing server data to my NAS world? I would like to preserve the world I run from my PC currently just migrate it over to the NAS rather than creating an entirely new world.

    Thanks very much for putting in the time to set this tutorial up, very helpful!

  13. francois adams francois adams

    Nice tuto & docker image, thanks !

Leave a Reply

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