docs: provide usage guide with highlightings around security (#96)

Author: Djaytan

README.md

@@ -1,4 +1,4 @@
-<h1 align="center">Docker PaperMC Server</h1>
+<h1 align="center">🐳 Docker PaperMC Server</h1>
 
 <div align="center">
 
@@ -15,6 +15,32 @@ Available in [Docker Hub](https://hub.docker.com/r/djaytan/papermc-server).
 
 </div>
 
+## 📘 Usage
+
+For production-grade deployments, it is recommended to use the following command:
+
+```bash
+$ docker run -it \
+  --name papermc-server \
+  --restart=on-failure:10 \
+  --cap-drop all \
+  --security-opt no-new-privileges \
+  --ulimit nofile=16384 \
+  --ulimit nproc=4096 \
+  --ulimit core=0 \
+  --cpus=4 \
+  --memory=8GB \
+  -p 25565:25565/tcp -p 25565:25565/udp \
+  -e EULA=true \
+  'djaytan/papermc-server:1.21.4'
+```
+
+_**Note:** These settings provide sensible defaults, but you may need to adjust them based on your server's specific requirements._
+
+Details about security best practices and recommendations can be found [here](docs/security-best-practices.md).
+
+Available tags can be found [here](https://hub.docker.com/r/djaytan/papermc-server/tags).
+
 ## ✨ Features
 
 * **[Alpine](https://hub.docker.com/_/alpine)-based image**
@@ -39,8 +65,9 @@ The image is under active development, with the following enhancements planned:
 * **Enable/Disable Aikar's flags**: Aikar's researches ([link](https://aikar.co/2018/07/02/tuning-the-jvm-g1gc-garbage-collector-flags-for-minecraft/)) and [PaperMC recommendations](https://docs.papermc.io/paper/aikars-flags/)
 * **Configurable TimeZone**
 * **Auto-updating builds**: Scheduled rebuilds for including upstream JDK/PaperMC updates and security patches.
-* **Compliancy with [OWASP Docker rules](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html)**
 * **GraalVM variant**
+* **Read-only filesystem**
+* **Helm chart**
 
 The below features may be implemented too, but are not a priority:
 

docs/GUIDE.md docs/security-best-practices.mddocs/GUIDE.md renamed to docs/security-best-practices.md

@@ -1,11 +1,15 @@
-# Guide
+²# Security Best Practices
 
-This guide helps you make the most of the OCI image, with a focus on compatibility and security.
+This guide provides practical instructions for optimizing the OCI image, with an emphasis on ensuring both compatibility and security.
 
 ## OWASP - Docker Security Cheat Sheet
 
-The [OWASP Docker Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html) provides a comprehensive overview of
-best practices that we recommend you to follow when running the PaperMC server container.
+The [OWASP Docker Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html) offers a thorough guide to securing
+Docker containers. We strongly recommend following these best practices when running the PaperMC server container.
+
+In the following sections, we’ll explain how to implement some of these recommendations specifically for this image.
+
+_**Note:** Making the filesystem read-only is not yet fully supported in this image._
 
 ## UID/GID
 
@@ -22,6 +26,14 @@ writable (`o+r`, `o+rw`) modes.
 For more details about OpenShift’s Security Context Constraints (SCCs), refer to
 the [official documentation](https://docs.openshift.com/container-platform/latest/concepts/policy/security-context-constraints.html).
 
+## Linux Kernel Capabilities & Privileges
+
+It is recommended to drop all Linux kernel capabilities, as this enhances security without affecting the container’s functionality. The PaperMC server does not
+require any special privileges, so this should not cause issues for most workloads. However, if you encounter specific problems, you can re-enable individual
+capabilities as needed.
+
+Additionally, disabling privilege escalation tools like `su` and `sudo` is recommended to further restrict potential security risks.
+
 ## Resource Limits
 
 Setting appropriate resource limits is essential to ensure the container behaves reliably, securely, and within predictable boundaries. This aligns with [OWASP

localdev.sh

@@ -1,7 +1,4 @@
 #!/usr/bin/env sh
-# TODO: document security recommendations adapted to this project
-# TODO: document requirements for OWASP RULE#8 https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html#rule-7-limit-resources-memory-cpu-file-descriptors-processes-restarts
-# TODO: try OWASP RULE#8 here
 
 set -eu