Merge pull request #1969 from ipfs/docs/document-container-limits

docs: docker container limits

Author: 2color

.github/styles/pln-ignore.txt

@@ -195,6 +195,8 @@ reproviding
 requesters
 retrievability
 roadmaps
+runtime
+runtime's
 rsa
 sandboxed
 satoshi
@@ -216,7 +218,7 @@ testground
 testnet
 toolkits
 trustlessly
-uncensorable 
+uncensorable
 undialable
 uniswap
 unreachability

docs/install/run-ipfs-inside-docker.md

@@ -1,6 +1,7 @@
 ---
 title: Install IPFS Kubo inside Docker
 description: You can run IPFS inside Docker to simplify your deployment processes, and horizontally scale your IPFS infrastructure.
+current-ipfs-version: v0.32.1
 ---
 
 # Install IPFS Kubo inside Docker
@@ -20,7 +21,7 @@ You can run Kubo IPFS inside Docker to simplify your deployment processes, as we
 1. Start a container running ipfs and expose ports `4001` (P2P TCP/QUIC transports), `5001` (RPC API) and `8080` (Gateway):
 
     ```shell
-    docker run -d --name ipfs_host -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:latest
+    docker run -d --name ipfs_host -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:v0.32.1
     ```
 
     ::: danger NEVER EXPOSE THE RPC API TO THE PUBLIC INTERNET
@@ -70,7 +71,7 @@ You can run Kubo IPFS inside Docker to simplify your deployment processes, as we
 When starting a container running ipfs for the first time with an empty data directory, it will call `ipfs init` to initialize configuration files and generate a new keypair. At this time, you can choose which profile to apply using the `IPFS_PROFILE` environment variable:
 
 ```shell
-docker run -d --name ipfs_host -e IPFS_PROFILE=server -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:latest
+docker run -d --name ipfs_host -e IPFS_PROFILE=server -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:v0.32.1
 ```
 
 ## Customizing your node
@@ -105,19 +106,35 @@ docker run -d --name ipfs \
 See the `gateway` example on the [go-ipfs-docker-examples repository](https://github.com/ipfs-shipyard/go-ipfs-docker-examples)
 :::
 
+## Configuring resource limits
+
+When deploying IPFS Kubo in containerized environments, it's crucial to align the Go runtime's resource awareness with the container's defined resource constraints via environment variables:
+
+- `GOMAXPROCS`: Configures the maximum number of OS threads that can execute Go code concurrently (should not be bigger than the hard container limit set via `docker --cpus`)
+- `GOMEMLIMIT`: Sets the soft [memory allocation limit for the Go runtime](https://tip.golang.org/doc/gc-guide#Memory_limit) (should be slightly below the hard limit set for container via `docker --memory`)
+
+Example:
+
+```shell
+docker run # (....)
+    --cpus="4.0" -e GOMAXPROCS=4 \
+    --memory="8000m" -e GOMEMLIMIT=7500MiB \
+    ipfs/kubo:v0.32.1
+```
+
 ## Private swarms inside Docker
 
 It is possible to initialize the container with a swarm key file (`/data/ipfs/swarm.key`) using the variables `IPFS_SWARM_KEY` and `IPFS_SWARM_KEY_FILE`. The `IPFS_SWARM_KEY` creates `swarm.key` with the contents of the variable itself, while `IPFS_SWARM_KEY_FILE` copies the key from a path stored in the variable. The `IPFS_SWARM_KEY_FILE` **overwrites** the key generated by `IPFS_SWARM_KEY`.
 
 ```shell
-docker run -d --name ipfs_host -e IPFS_SWARM_KEY=<your swarm key> -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:latest
+docker run -d --name ipfs_host -e IPFS_SWARM_KEY=<your swarm key> -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:v0.32.1
 ```
 
 The swarm key initialization can also be done using docker secrets, and requires `docker swarm` or `docker-compose`:
 
 ```shell
 cat your_swarm.key | docker secret create swarm_key_secret -
-docker run -d --name ipfs_host --secret swarm_key_secret -e IPFS_SWARM_KEY_FILE=/run/secrets/swarm_key_secret -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:latest
+docker run -d --name ipfs_host --secret swarm_key_secret -e IPFS_SWARM_KEY_FILE=/run/secrets/swarm_key_secret -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 4001:4001 -p 4001:4001/udp -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 ipfs/kubo:v0.32.1
 ```
 
 ## Key rotation inside Docker
@@ -126,10 +143,10 @@ It is possible to do key rotation in an ephemeral container that is temporarily
 
 ```shell
 # given container named 'ipfs-test' that persists repo at /path/to/persisted/.ipfs
-docker run -d --name ipfs-test -v /path/to/persisted/.ipfs:/data/ipfs ipfs/kubo:latest
+docker run -d --name ipfs-test -v /path/to/persisted/.ipfs:/data/ipfs ipfs/kubo:v0.32.1
 docker stop ipfs-test  
 
 # key rotation works like this (old key saved under 'old-self')
-docker run --rm -it -v /path/to/persisted/.ipfs:/data/ipfs ipfs/kubo:latest key rotate -o old-self -t ed25519
+docker run --rm -it -v /path/to/persisted/.ipfs:/data/ipfs ipfs/kubo:v0.32.1 key rotate -o old-self -t ed25519
 docker start ipfs-test # will start with the new key
 ```