From fb2ab824072d27387cfedaab5b567c61c59cb6cf Mon Sep 17 00:00:00 2001 From: Rela Vergis Date: Thu, 15 Jun 2023 20:26:33 -0400 Subject: [PATCH 1/6] Added full working example on docs with link in intro --- docs/index.md | 3 + .../deployment/docker-compose-full-example.md | 91 +++++++++++++++++++ 2 files changed, 94 insertions(+) create mode 100644 docs/misc/deployment/docker-compose-full-example.md diff --git a/docs/index.md b/docs/index.md index 791fd2b6114..2f0cf0e8424 100644 --- a/docs/index.md +++ b/docs/index.md @@ -59,5 +59,8 @@ To apply changes made to the compose file, just run `docker compose up -d` again Follow the logs of the container using `docker compose logs -f`, check on the status with `docker compose ps`, and stop the container using `docker compose stop`. +!!! note "Full Setup Example" + Here is a [reference guide to setting up a server from scratch using docker compose](https://docker-minecraft-server.readthedocs.io/en/latest/misc/deployment/docker-compose-full-example/). + !!! note "More Examples" There are more [examples located in the Github repo](https://github.com/itzg/docker-minecraft-server/tree/master/examples). \ No newline at end of file diff --git a/docs/misc/deployment/docker-compose-full-example.md b/docs/misc/deployment/docker-compose-full-example.md new file mode 100644 index 00000000000..d2781309dcc --- /dev/null +++ b/docs/misc/deployment/docker-compose-full-example.md @@ -0,0 +1,91 @@ +# Full Tutorial for Server Setup using Docker Compose + +This is a reference guide/tutorial on how to set up a Minecraft server using this project and docker-compose. Some parts of this tutorial will make mention of operating system-dependent methods and may or may not provide the specific workflow for your OS (e.g. Windows, Mac, Linux, etc.). Please access the many readily available online resources on how to perform these steps. + +## 1. Set RCON_PASSWORD passphrase (if you plan to use RCON) + +The very first and most important thing to mention is that creating a Minecraft server comes with security risks, and by creating a Minecraft server using any method at all, you accept these risks. *Understanding what these risks are and how to minimize your risk is of the utmost importance.* + +RCON is enabled by default to perform accessory functions of this project. Without an RCON password set, it will be set to a randomized value each time you start the server. If you plan to use an RCON password (which might be sensible if you plan to use RCON), then you should set this first before anything else for convenience and because it will improve your server setup workflow. **DO NOT reuse a passphrase that you use for anything else, as this poses a significant security risk.** It is better is to memorize your passphrase rather than putting it anywhere, but if you do, guard it like you would any other passphrase by putting it in a safe place - *don't place it directly in your server folder*. + +## 2. Enable Virtualization. + +The second step is to enable virtualization (this varies by System). First, check if you already have virtualization enabled - please follow the appropriate steps according to your operating system. Specific steps are out of scope for the purposes of this tutorial, but if you find that you do not have virtualization enabled, you will need to enable it in this step for Docker to work. + +## 3. Download Docker Desktop. + +You may navigate to [this page to download Docker Desktop](https://www.docker.com/products/docker-desktop/). It is required to run this project. + +## 4. Create a New Server Directory + +Create a new folder and name it something recognizable (such as "minecraft-server", for example). You may either use the command line, or your system's file manager GUI. + +## 5. Create and Populate docker-compose.yml File in the Server Directory + +The most important part of the docker-compose.yml creation step is to make sure that your docker-compose.yml file is properly formatted. One potential example docker-compose.yml file is as follows (be sure to delete any irrelevant lines to your application, or add any that you may need before copying and pasting the file contents). Be sure that the indentation is correct for every part of the file. + +!!!note + One common pitfall may be that during the creation of your docker-compose.yml file, your text editing application (if using TextEdit for example) may add a .txt extension to your file - *this will render it unfindable by docker-compose: your docker-compose.yml file must actually be of the YAML type*. + +```yaml +version: "3.8" +# Other docker-compose examples in /examples + +services: + minecraft: + image: itzg/minecraft-server + ports: + - "25565:25565" + volumes: + - "mc:/data" + environment: + EULA: "TRUE" + ENABLE_RCON: "true" + RCON_PORT: 28016 + # enable env variable replacement + REPLACE_ENV_VARIABLES: "TRUE" + # define an optional prefix for your env variables you want to replace + ENV_VARIABLE_PREFIX: "CFG_" + # and here are the actual variables + CFG_DB_HOST: "http://localhost:3306" + CFG_DB_NAME: "minecraft" + CFG_DB_PASSWORD_FILE: "/run/secrets/db_password" + +volumes: + mc: + rcon: + +secrets: + db_password: + file: ./db_password +``` + +## 6. Use docker-compose to Start Server + +This is this simplest part of the server setup. Simply run the command `docker compose up -d` and docker compose will set up and serve a Minecraft server. + +## 7. Find Your Client IP Address + +Your server should now be running on your client (and, as of now, won't be accessible to the outside world) - you may view the logs through either the terminal or the terminal tab within Docker. The server will be running on your computer client on the port specified within your docker-compose.yml file. As such, you will need to expose one of your ports. To do this, you will need to port-forward your server client's (for example, your desktop's or otherwise your server machine's) IP address with the port that your server is using. To do this, first find your IP address: this process varies by operating system - + +- On Windows, open your command line application of choice and type in `ipconfig --all` - find your IPv4 address and use that as your IP address. + +- On Mac, open your terminal and type in `ipconfig getifaddr en0` - the output will be your IP address. + +- On Linux, simply the `ip` command will output your relevant IP address. + +## 8. Port-forward using Router + +!!! warning + In general, please **DO NOT** expose your RCON port externally (unless you are doing so intentionally with a full understanding of what that means and what it entails). + +First, log into your router settings page. Many routers use an IP address of `192.168.1.1`, but make sure you check what it is: this process may vary by operating system. To log in to your router settings page, simply type your router IP address directly into your preferred internet browser (e.g. Chrome, Firefox, Edge). Then, look for your Port-forwarding setting: this will be router/manufacturer-dependent, so look for specific instructions on how to access this setting. Forward the port that you have specified in your docker-compose.yml. Once you have done this, your server should be working and accessible to anyone with the address. + +## 9. Test and Monitor for Errors, Changes, or Unusual Activity + +Your Minecraft Server should now be accessible to the outside world on the exact IP Address:Port pair that you forwarded when you port-forwarded in the previous step (e.g. `192.168.1.1:25565`). You may test this by entering Minecraft and directly connecting using the aforementioned address or by adding the server in the Multiplayer tab, and making sure that the server is accessible. + +!!! warning + It is not recommended to share this IP address widely: it is the IP address that corresponds to your machine - sharing it widely could expose it to security threats. + +Follow the logs of the container using `docker compose logs -f`, check on the status with `docker compose ps`, and stop the container using `docker compose stop`. From 08f3cd6f47b974bce9d6b446efeba060f1d75033 Mon Sep 17 00:00:00 2001 From: rela Date: Thu, 15 Jun 2023 20:57:02 -0400 Subject: [PATCH 2/6] fixed missing space --- docs/misc/deployment/docker-compose-full-example.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/misc/deployment/docker-compose-full-example.md b/docs/misc/deployment/docker-compose-full-example.md index d2781309dcc..7e841e7512d 100644 --- a/docs/misc/deployment/docker-compose-full-example.md +++ b/docs/misc/deployment/docker-compose-full-example.md @@ -24,7 +24,7 @@ Create a new folder and name it something recognizable (such as "minecraft-serve The most important part of the docker-compose.yml creation step is to make sure that your docker-compose.yml file is properly formatted. One potential example docker-compose.yml file is as follows (be sure to delete any irrelevant lines to your application, or add any that you may need before copying and pasting the file contents). Be sure that the indentation is correct for every part of the file. -!!!note +!!! note One common pitfall may be that during the creation of your docker-compose.yml file, your text editing application (if using TextEdit for example) may add a .txt extension to your file - *this will render it unfindable by docker-compose: your docker-compose.yml file must actually be of the YAML type*. ```yaml From 2f45cfb1c9d20ff09fe777dfa9c709daf7a13fbf Mon Sep 17 00:00:00 2001 From: rela <136220062+rela-v@users.noreply.github.com> Date: Fri, 16 Jun 2023 10:54:19 -0400 Subject: [PATCH 3/6] Apply suggestions from code review accepting initial changes, will continue to revise and post dev.to article -- awaiting guidance on link location. Co-authored-by: Geoff Bourne --- docs/index.md | 2 +- docs/misc/deployment/docker-compose-full-example.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 2f0cf0e8424..254e4b37551 100644 --- a/docs/index.md +++ b/docs/index.md @@ -60,7 +60,7 @@ To apply changes made to the compose file, just run `docker compose up -d` again Follow the logs of the container using `docker compose logs -f`, check on the status with `docker compose ps`, and stop the container using `docker compose stop`. !!! note "Full Setup Example" - Here is a [reference guide to setting up a server from scratch using docker compose](https://docker-minecraft-server.readthedocs.io/en/latest/misc/deployment/docker-compose-full-example/). + Here is a [reference guide to setting up a server from scratch using docker compose](misc/deployment/docker-compose-full-example/). !!! note "More Examples" There are more [examples located in the Github repo](https://github.com/itzg/docker-minecraft-server/tree/master/examples). \ No newline at end of file diff --git a/docs/misc/deployment/docker-compose-full-example.md b/docs/misc/deployment/docker-compose-full-example.md index 7e841e7512d..48c27f48a49 100644 --- a/docs/misc/deployment/docker-compose-full-example.md +++ b/docs/misc/deployment/docker-compose-full-example.md @@ -1,4 +1,4 @@ -# Full Tutorial for Server Setup using Docker Compose +# From zero using Docker Desktop and Compose This is a reference guide/tutorial on how to set up a Minecraft server using this project and docker-compose. Some parts of this tutorial will make mention of operating system-dependent methods and may or may not provide the specific workflow for your OS (e.g. Windows, Mac, Linux, etc.). Please access the many readily available online resources on how to perform these steps. From d40ecb6aebedac86d42462846f746e5a1e1f9a6c Mon Sep 17 00:00:00 2001 From: rela Date: Fri, 16 Jun 2023 11:24:30 -0400 Subject: [PATCH 4/6] added all suggested changes --- .../deployment/docker-compose-full-example.md | 30 ++++--------------- 1 file changed, 6 insertions(+), 24 deletions(-) diff --git a/docs/misc/deployment/docker-compose-full-example.md b/docs/misc/deployment/docker-compose-full-example.md index 48c27f48a49..c31d27851a3 100644 --- a/docs/misc/deployment/docker-compose-full-example.md +++ b/docs/misc/deployment/docker-compose-full-example.md @@ -1,4 +1,5 @@ -# From zero using Docker Desktop and Compose +# Zero to Minecraft Server +## with Docker Desktop and Compose This is a reference guide/tutorial on how to set up a Minecraft server using this project and docker-compose. Some parts of this tutorial will make mention of operating system-dependent methods and may or may not provide the specific workflow for your OS (e.g. Windows, Mac, Linux, etc.). Please access the many readily available online resources on how to perform these steps. @@ -40,39 +41,21 @@ services: - "mc:/data" environment: EULA: "TRUE" - ENABLE_RCON: "true" - RCON_PORT: 28016 - # enable env variable replacement - REPLACE_ENV_VARIABLES: "TRUE" - # define an optional prefix for your env variables you want to replace - ENV_VARIABLE_PREFIX: "CFG_" - # and here are the actual variables - CFG_DB_HOST: "http://localhost:3306" - CFG_DB_NAME: "minecraft" - CFG_DB_PASSWORD_FILE: "/run/secrets/db_password" - -volumes: - mc: - rcon: - -secrets: - db_password: - file: ./db_password ``` ## 6. Use docker-compose to Start Server This is this simplest part of the server setup. Simply run the command `docker compose up -d` and docker compose will set up and serve a Minecraft server. -## 7. Find Your Client IP Address +## 7. Find Your Host IP Address -Your server should now be running on your client (and, as of now, won't be accessible to the outside world) - you may view the logs through either the terminal or the terminal tab within Docker. The server will be running on your computer client on the port specified within your docker-compose.yml file. As such, you will need to expose one of your ports. To do this, you will need to port-forward your server client's (for example, your desktop's or otherwise your server machine's) IP address with the port that your server is using. To do this, first find your IP address: this process varies by operating system - +Your server should now be running on your client (and, as of now, won't be accessible to the outside world) - you may view the logs through either the terminal or the terminal tab within Docker. Alternatively, you may issue the command `docker logs ` to view the logs; adding the `-f` flag will allow you to follow the logs in real-time. The server will be running on your computer client on the port specified within your docker-compose.yml file. As such, you will need to expose one of your ports. To do this, you will need to port-forward your server client's (for example, your desktop's or otherwise your server machine's) IP address with the port that your server is using. To do this, first find your IP address: this process varies by operating system - - On Windows, open your command line application of choice and type in `ipconfig --all` - find your IPv4 address and use that as your IP address. - On Mac, open your terminal and type in `ipconfig getifaddr en0` - the output will be your IP address. -- On Linux, simply the `ip` command will output your relevant IP address. +- On Linux, use the command `ip r | grep default`: this will give you your relevant IP address, which is the `via` value in the output. ## 8. Port-forward using Router @@ -86,6 +69,5 @@ First, log into your router settings page. Many routers use an IP address of `19 Your Minecraft Server should now be accessible to the outside world on the exact IP Address:Port pair that you forwarded when you port-forwarded in the previous step (e.g. `192.168.1.1:25565`). You may test this by entering Minecraft and directly connecting using the aforementioned address or by adding the server in the Multiplayer tab, and making sure that the server is accessible. !!! warning - It is not recommended to share this IP address widely: it is the IP address that corresponds to your machine - sharing it widely could expose it to security threats. + It is not recommended to share this IP address widely: it is the IP address that corresponds to your home network's access point: sharing indiscriminately may expose your home network to security threats. -Follow the logs of the container using `docker compose logs -f`, check on the status with `docker compose ps`, and stop the container using `docker compose stop`. From 36150683146b80de8775f1a462f85b9d9838dc12 Mon Sep 17 00:00:00 2001 From: rela Date: Fri, 16 Jun 2023 14:57:07 -0400 Subject: [PATCH 5/6] per recommendation, added index.md in docs/misc/deployment/ with link to external dev.to article --- .../deployment/docker-compose-full-example.md | 73 ------------------- docs/misc/deployment/index.md | 10 +++ 2 files changed, 10 insertions(+), 73 deletions(-) delete mode 100644 docs/misc/deployment/docker-compose-full-example.md create mode 100644 docs/misc/deployment/index.md diff --git a/docs/misc/deployment/docker-compose-full-example.md b/docs/misc/deployment/docker-compose-full-example.md deleted file mode 100644 index c31d27851a3..00000000000 --- a/docs/misc/deployment/docker-compose-full-example.md +++ /dev/null @@ -1,73 +0,0 @@ -# Zero to Minecraft Server -## with Docker Desktop and Compose - -This is a reference guide/tutorial on how to set up a Minecraft server using this project and docker-compose. Some parts of this tutorial will make mention of operating system-dependent methods and may or may not provide the specific workflow for your OS (e.g. Windows, Mac, Linux, etc.). Please access the many readily available online resources on how to perform these steps. - -## 1. Set RCON_PASSWORD passphrase (if you plan to use RCON) - -The very first and most important thing to mention is that creating a Minecraft server comes with security risks, and by creating a Minecraft server using any method at all, you accept these risks. *Understanding what these risks are and how to minimize your risk is of the utmost importance.* - -RCON is enabled by default to perform accessory functions of this project. Without an RCON password set, it will be set to a randomized value each time you start the server. If you plan to use an RCON password (which might be sensible if you plan to use RCON), then you should set this first before anything else for convenience and because it will improve your server setup workflow. **DO NOT reuse a passphrase that you use for anything else, as this poses a significant security risk.** It is better is to memorize your passphrase rather than putting it anywhere, but if you do, guard it like you would any other passphrase by putting it in a safe place - *don't place it directly in your server folder*. - -## 2. Enable Virtualization. - -The second step is to enable virtualization (this varies by System). First, check if you already have virtualization enabled - please follow the appropriate steps according to your operating system. Specific steps are out of scope for the purposes of this tutorial, but if you find that you do not have virtualization enabled, you will need to enable it in this step for Docker to work. - -## 3. Download Docker Desktop. - -You may navigate to [this page to download Docker Desktop](https://www.docker.com/products/docker-desktop/). It is required to run this project. - -## 4. Create a New Server Directory - -Create a new folder and name it something recognizable (such as "minecraft-server", for example). You may either use the command line, or your system's file manager GUI. - -## 5. Create and Populate docker-compose.yml File in the Server Directory - -The most important part of the docker-compose.yml creation step is to make sure that your docker-compose.yml file is properly formatted. One potential example docker-compose.yml file is as follows (be sure to delete any irrelevant lines to your application, or add any that you may need before copying and pasting the file contents). Be sure that the indentation is correct for every part of the file. - -!!! note - One common pitfall may be that during the creation of your docker-compose.yml file, your text editing application (if using TextEdit for example) may add a .txt extension to your file - *this will render it unfindable by docker-compose: your docker-compose.yml file must actually be of the YAML type*. - -```yaml -version: "3.8" -# Other docker-compose examples in /examples - -services: - minecraft: - image: itzg/minecraft-server - ports: - - "25565:25565" - volumes: - - "mc:/data" - environment: - EULA: "TRUE" -``` - -## 6. Use docker-compose to Start Server - -This is this simplest part of the server setup. Simply run the command `docker compose up -d` and docker compose will set up and serve a Minecraft server. - -## 7. Find Your Host IP Address - -Your server should now be running on your client (and, as of now, won't be accessible to the outside world) - you may view the logs through either the terminal or the terminal tab within Docker. Alternatively, you may issue the command `docker logs ` to view the logs; adding the `-f` flag will allow you to follow the logs in real-time. The server will be running on your computer client on the port specified within your docker-compose.yml file. As such, you will need to expose one of your ports. To do this, you will need to port-forward your server client's (for example, your desktop's or otherwise your server machine's) IP address with the port that your server is using. To do this, first find your IP address: this process varies by operating system - - -- On Windows, open your command line application of choice and type in `ipconfig --all` - find your IPv4 address and use that as your IP address. - -- On Mac, open your terminal and type in `ipconfig getifaddr en0` - the output will be your IP address. - -- On Linux, use the command `ip r | grep default`: this will give you your relevant IP address, which is the `via` value in the output. - -## 8. Port-forward using Router - -!!! warning - In general, please **DO NOT** expose your RCON port externally (unless you are doing so intentionally with a full understanding of what that means and what it entails). - -First, log into your router settings page. Many routers use an IP address of `192.168.1.1`, but make sure you check what it is: this process may vary by operating system. To log in to your router settings page, simply type your router IP address directly into your preferred internet browser (e.g. Chrome, Firefox, Edge). Then, look for your Port-forwarding setting: this will be router/manufacturer-dependent, so look for specific instructions on how to access this setting. Forward the port that you have specified in your docker-compose.yml. Once you have done this, your server should be working and accessible to anyone with the address. - -## 9. Test and Monitor for Errors, Changes, or Unusual Activity - -Your Minecraft Server should now be accessible to the outside world on the exact IP Address:Port pair that you forwarded when you port-forwarded in the previous step (e.g. `192.168.1.1:25565`). You may test this by entering Minecraft and directly connecting using the aforementioned address or by adding the server in the Multiplayer tab, and making sure that the server is accessible. - -!!! warning - It is not recommended to share this IP address widely: it is the IP address that corresponds to your home network's access point: sharing indiscriminately may expose your home network to security threats. - diff --git a/docs/misc/deployment/index.md b/docs/misc/deployment/index.md new file mode 100644 index 00000000000..fe47031b049 --- /dev/null +++ b/docs/misc/deployment/index.md @@ -0,0 +1,10 @@ +## Supporting Articles + +Below are supporting articles for server deployment. + + +- "Zero to Minecraft Server with Docker Desktop and Compose" + + https://dev.to/rela-v/zero-to-minecraft-server-with-docker-desktop-and-compose-500a + + - This is a reference guide/tutorial on how to set up a vanilla Minecraft server using this project. From 3fd4addd4ded62ccc7f0e907c8b3d0026ea1bbb1 Mon Sep 17 00:00:00 2001 From: rela Date: Fri, 16 Jun 2023 14:58:59 -0400 Subject: [PATCH 6/6] added longer blurb --- docs/misc/deployment/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/misc/deployment/index.md b/docs/misc/deployment/index.md index fe47031b049..21e7c36e0c1 100644 --- a/docs/misc/deployment/index.md +++ b/docs/misc/deployment/index.md @@ -7,4 +7,4 @@ Below are supporting articles for server deployment. https://dev.to/rela-v/zero-to-minecraft-server-with-docker-desktop-and-compose-500a - - This is a reference guide/tutorial on how to set up a vanilla Minecraft server using this project. + - This is a reference guide/tutorial on how to set up a vanilla Minecraft server using this project, including step-by-step instructions, and information on topics such as port-forwarding.