Fix shellcheck warnings in entrypoint scripts

- Add shellcheck disable=SC1091 for dynamic source paths
- Quote INSTALLED_DIRECTORY variables to prevent word splitting
- Resolves all reported shellcheck issues in PR review

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

.github/workflows/docker-build.yml

@@ -15,7 +15,7 @@ jobs:
     steps:
 
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3

.github/workflows/docker-description.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Docker Hub Description
         uses: peter-evans/dockerhub-description@v4.0.2

.github/workflows/lint.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: shellcheck
         uses: reviewdog/action-shellcheck@v1
@@ -23,7 +23,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: hadolint
         uses: reviewdog/action-hadolint@v1

.github/workflows/update.yml

@@ -12,7 +12,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           token: ${{ secrets.REPO_TOKEN }}
 

PERMISSION_ISSUES_GUIDE.md

@@ -0,0 +1,408 @@
+# Factorio Docker Permission Issues - Solutions and Workarounds
+
+This document provides comprehensive solutions and workarounds for permission-related issues in the Factorio Docker container, based on detailed analysis of issues #558, #556, #555, #549, #496, #501, #492, and #420.
+
+## Table of Contents
+- [Root Cause Analysis](#root-cause-analysis)
+- [Critical Prerequisites](#critical-prerequisites)
+- [General Solutions](#general-solutions)
+- [Platform-Specific Issues](#platform-specific-issues)
+- [Docker System Requirements](#docker-system-requirements)
+- [Advanced Troubleshooting](#advanced-troubleshooting)
+- [Known Issues and Limitations](#known-issues-and-limitations)
+
+## Root Cause Analysis
+
+Based on detailed investigation by maintainer @Fank and community reports, the permission issues stem from:
+
+1. **Container Architecture Issues**:
+   - No `USER` directive in Dockerfile despite creating a factorio user
+   - Container starts as root and performs recursive `chown` on every start
+   - The recursive `chown -R factorio:factorio /factorio` can be interrupted, leaving inconsistent permissions
+   - Dynamic UID/GID mapping using PUID/PGID environment variables adds complexity
+
+2. **Rootless Docker Complications**:
+   - UID namespace remapping (e.g., container UID 845 → host UID 100844)
+   - Rootless Docker daemons cannot change ownership of bind-mounted volumes
+   - Different rootless implementations use different UID mappings
+
+3. **Host System Dependencies**:
+   - Older Docker versions (especially pre-20.x) have permission handling bugs
+   - Some kernel versions have issues with user namespace operations
+   - SELinux and AppArmor can interfere with volume permissions
+
+## Critical Prerequisites
+
+### Update Your System First!
+Many permission issues are caused by outdated system components:
+
+```bash
+# For Ubuntu/Debian
+sudo apt-get update
+sudo apt-get upgrade
+
+# Specifically update Docker to 27.x or newer
+# Follow: https://docs.docker.com/engine/install/ubuntu/#install-docker-engine
+```
+
+**Important**: Multiple users reported that updating Docker resolved their "Operation not permitted" errors.
+
+## General Solutions
+
+### Solution A: Pre-create Directories with Correct Permissions
+```bash
+# Create the directory structure
+sudo mkdir -p /opt/factorio/{saves,mods,config,scenarios,script-output}
+
+# Set ownership to factorio user (845:845)
+sudo chown -R 845:845 /opt/factorio
+
+# Set appropriate permissions (note the 'u+rwx' for write access)
+sudo chmod -R u+rwx /opt/factorio
+```
+
+### Solution B: Use the Rootless Docker Image (Recommended)
+The project now provides a rootless variant that runs as UID 1000, which avoids most permission issues:
+```bash
+docker run -d \
+  -p 34197:34197/udp \
+  -p 27015:27015/tcp \
+  -v /opt/factorio:/factorio \
+  --name factorio \
+  factoriotools/factorio:latest-rootless
+```
+
+**Benefits of rootless images**:
+- No `chown` operations on startup
+- No need to pre-create directories with specific permissions
+- Works seamlessly with rootless Docker installations
+- Avoids the recursive permission changes that can be interrupted
+
+**Available rootless tags**:
+- `latest-rootless`
+- `stable-rootless`
+- `2.0.55-rootless` (or any specific version with `-rootless` suffix)
+
+## Platform-Specific Issues and Solutions
+
+### NixOS with Rootless Docker
+
+**Problem**: Permission denied errors when creating directories, even after setting ownership to 845:845. Files show ownership by UID 100844 instead of 845.
+
+**Solutions**:
+1. **Find and use your actual rootless Docker user ID**:
+   ```bash
+   # Method 1: Check your user ID
+   id -u
+   
+   # Method 2: Check existing Docker volumes for the UID Docker is using
+   ls -lan /path/to/other/docker/volumes
+   
+   # Common rootless Docker UIDs:
+   # - 100999 (NixOS default)
+   # - 100844 (as reported in issue #558)
+   # - 1000 (some configurations)
+   
+   # Apply the correct ownership
+   sudo chown -R 100999:100999 ./factorio
+   ```
+
+2. **Configure NixOS Docker properly**:
+   ```nix
+   # In configuration.nix
+   virtualisation.docker.rootless = {
+     enable = true;
+     setSocketVariable = true;
+   };
+   ```
+
+3. **Port Mapping Issues**: Rootless Docker on NixOS has issues with userland-proxy that can cause random port assignments. Consider using host networking if possible.
+
+### macOS with Colima
+
+**Problem**: `copy_file` permission denied errors, even with correct ownership. Permission errors when running docker-dlc.sh.
+
+**Solutions**:
+1. **Set broader permissions before mounting**:
+   ```bash
+   # Create directory structure
+   mkdir -p ./factorio-server/{saves,mods,config,scenarios}
+   
+   # Set ownership AND permissions
+   sudo chown -R 845:845 ./factorio-server
+   sudo chmod -R 775 ./factorio-server
+   ```
+
+2. **Use Docker Desktop instead of Colima** if the issues persist, as it has better macOS integration
+
+3. **Specify PUID/PGID explicitly**:
+   ```yaml
+   environment:
+     - PUID=502  # Common macOS user ID
+     - PGID=20   # Common macOS staff group
+   ```
+
+### Windows
+
+**Problem**: Cannot remove temporary locale files due to Windows-Linux permission translation. Errors like "Permission denied trying to remove /factorio/temp/currently-playing/locale/de".
+
+**Solutions**:
+1. **Use WSL2 backend** for Docker Desktop (required for proper Linux filesystem semantics)
+
+2. **Store volumes in WSL2 filesystem** instead of Windows filesystem:
+   ```bash
+   # Inside WSL2 terminal
+   mkdir -p ~/factorio
+   chmod -R 777 ~/factorio
+   ```
+   
+   ```yaml
+   # docker-compose.yml - use WSL2 path
+   volumes:
+     - ~/factorio:/factorio
+   ```
+
+3. **Avoid Windows drive mounts** (like `W:\docker\factorio`) as they have inherent permission translation issues
+
+4. **Add :Z flag for SELinux context** (some Windows Docker setups benefit from this):
+   ```yaml
+   volumes:
+     - ~/factorio:/factorio:Z
+   ```
+
+### Synology NAS
+
+**Problem**: Permission denied when accessing mounted volumes. Error: "filesystem error: status: Permission denied [/factorio/saves]".
+
+**Solutions**:
+1. **Create and set permissions via SSH**:
+   ```bash
+   # SSH into Synology
+   sudo mkdir -p /volume1/docker/factorio
+   sudo chown -R 845:845 /volume1/docker/factorio
+   sudo chmod -R u+rwx /volume1/docker/factorio  # Important: u+rwx for write access
+   ```
+
+2. **Use the correct volume path in your container**:
+   ```bash
+   docker run -d \
+     -p 34197:34197/udp \
+     -p 27015:27015/tcp \
+     -v /volume1/docker/factorio:/factorio \
+     --name factorio \
+     --restart=always \
+     factoriotools/factorio
+   ```
+
+3. **Check DSM Docker permissions** - ensure the Docker package has proper permissions to the shared folder
+
+## Docker System Requirements
+
+### Minimum Docker Version
+Based on community reports, these Docker versions are known to work:
+- **Docker 27.4.1** - Confirmed working
+- **Docker 20.x+** - Generally stable
+- **Docker 19.x and below** - Known permission issues
+
+**Check your Docker version**:
+```bash
+docker --version
+# If below 20.x, update immediately!
+```
+
+### "Operation not permitted" at Util.cpp:81
+This specific error is often caused by:
+1. **Outdated Docker version** - Update Docker first!
+2. **Outdated kernel** - Run system updates
+3. **Missing kernel capabilities** - Check Docker daemon configuration
+
+## Docker Compose Best Practices
+
+### Basic Configuration
+```yaml
+version: '3'
+services:
+  factorio:
+    image: factoriotools/factorio:stable
+    container_name: factorio
+    ports:
+      - "34197:34197/udp"
+      - "27015:27015/tcp"
+    volumes:
+      - ./factorio:/factorio
+    restart: unless-stopped
+    stdin_open: true  # For interactive console
+    tty: true
+```
+
+### Advanced Configuration for Permission Issues
+```yaml
+version: '3'
+services:
+  factorio:
+    image: factoriotools/factorio:stable
+    container_name: factorio
+    ports:
+      - "34197:34197/udp"
+      - "27015:27015/tcp"
+    volumes:
+      - ./factorio:/factorio:Z  # :Z for SELinux systems
+    restart: unless-stopped
+    # user: "845:845"  # WARNING: This might break the entrypoint script
+    environment:
+      - PUID=845
+      - PGID=845
+      - UPDATE_MODS_ON_START=false  # Disable if having permission issues
+```
+
+### Rootless Docker Configuration
+```yaml
+version: '3'
+services:
+  factorio:
+    image: factoriotools/factorio:latest-rootless
+    container_name: factorio
+    ports:
+      - "34197:34197/udp"
+      - "27015:27015/tcp"
+    volumes:
+      - ./factorio:/factorio
+    restart: unless-stopped
+    environment:
+      - PUID=1000  # Rootless default
+      - PGID=1000
+```
+
+## Advanced Troubleshooting
+
+### Step-by-Step Diagnosis
+
+1. **Check Current Ownership**:
+   ```bash
+   ls -lan ./factorio
+   # Look for UIDs like 845, 1000, 100844, 100999
+   ```
+
+2. **Verify Docker User Mapping**:
+   ```bash
+   # Check what user the container is running as
+   docker exec factorio id
+   
+   # Check file ownership inside container
+   docker exec factorio ls -lan /factorio
+   ```
+
+3. **Test Without Volume Mount** (isolates host permission issues):
+   ```bash
+   docker run --rm -it factoriotools/factorio:stable
+   # If this works, the issue is with your host volume permissions
+   ```
+
+4. **Check Security Modules**:
+   ```bash
+   # SELinux (Fedora, RHEL, CentOS)
+   getenforce
+   # If "Enforcing", try adding :Z to volume mount
+   
+   # AppArmor (Ubuntu, Debian)
+   sudo apparmor_status | grep docker
+   ```
+
+5. **Debug the Entrypoint Script**:
+   ```bash
+   # Run with debug output
+   docker run --rm -it \
+     -e DEBUG=true \
+     -v ./factorio:/factorio \
+     factoriotools/factorio:stable
+   ```
+
+### Common Error Messages and Solutions
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Util.cpp:81: Operation not permitted` | Outdated Docker/kernel | Update Docker and system packages |
+| `chown: Operation not permitted` | Rootless Docker | Use rootless Docker UID for ownership |
+| `Permission denied [/factorio/saves]` | Wrong directory permissions | `chmod -R u+rwx` on host directory |
+| `Couldn't create lock file /factorio/.lock` | Container can't write to volume | Check volume mount and permissions |
+| `Map version X cannot be loaded` | Version mismatch | Use correct Docker image version |
+
+## Known Issues and Limitations
+
+### Interrupted chown Operations
+The container performs `chown -R factorio:factorio /factorio` on every start. If the container is killed during this operation:
+- Files will have inconsistent ownership
+- Some files owned by 845, others by different UIDs
+- Solution: Let the container complete startup before stopping
+
+### Rootless Docker Port Mapping
+**Issue #496**: Rootless Docker with userland-proxy causes random port assignments instead of the configured 34197.
+- **Workaround**: Use host networking mode if possible
+- **Note**: This is a Docker limitation, not specific to this image
+
+### Map Version Compatibility
+**Problem**: "Map version 2.0.23-0 cannot be loaded because it is higher than the game version".
+
+**Solution**: 
+```bash
+# Use a version that matches or exceeds your save
+docker pull factoriotools/factorio:2.0.23
+# Or always use latest for newest features
+docker pull factoriotools/factorio:latest
+```
+
+## Recommended Approach
+
+### For New Installations
+1. **Update your system first** - Many issues are caused by old Docker versions
+2. **Try the rootless image first** - It avoids most permission issues entirely
+3. **Pre-create directories** with correct permissions if using the standard image
+4. **Test without volumes** first to ensure the image works
+
+### For Existing Installations with Issues
+1. **Stop the container** and let it shut down cleanly
+2. **Backup your data** before making changes
+3. **Check Docker version** - update if below 20.x
+4. **Fix permissions** using the platform-specific solution
+5. **Consider rootless variant** for easier permission management
+
+### Best Practices
+- **Let the container start fully** before stopping (avoid interrupted chown)
+- **Use named volumes** instead of bind mounts when possible
+- **Monitor first startup** to ensure permissions are set correctly
+- **Keep Docker updated** to avoid known bugs
+
+## Community Solutions
+
+### Proposed Improvements (from @Fank)
+1. **Add USER directive** in Dockerfile after creating directories
+2. **Optimize chown logic** to only run when ownership is wrong
+3. **Implement fixuid** for better UID/GID mapping
+4. **Add health checks** to ensure permissions are correct before starting
+
+### Alternative Images
+Some users have tried other Factorio Docker images (e.g., goofball222/factorio) but report the same Util.cpp:81 errors, suggesting this is a broader ecosystem issue related to Docker versions and system configurations.
+
+## Quick Reference
+
+| Platform | Common UID | Recommended Approach |
+|----------|-----------|---------------------|
+| Standard Docker | 845 | Update Docker, use `chown 845:845` |
+| Rootless Docker (NixOS) | 100999, 100844 | Find actual UID, chown to that |
+| macOS (Docker Desktop) | 502 (user), 20 (staff) | Use PUID/PGID env vars |
+| Windows | N/A | Use WSL2 filesystem |
+| Synology NAS | varies | Check DSM user, ensure Docker has folder access |
+
+## Getting Help
+
+If these solutions don't work:
+1. **Update everything first** (Docker, kernel, system packages)
+2. **Provide full details** when reporting issues:
+   - Docker version (`docker --version`)
+   - OS and version
+   - Full error messages
+   - Output of `ls -lan` on your volume
+3. **Try the rootless image** as an alternative
+4. **Check issue #558** for ongoing discussions
+
+Remember: The vast majority of permission issues are resolved by updating Docker to version 20.x or newer!

README.md

@@ -6,17 +6,8 @@
 [中文](./README_zh_CN.md)
 
 <!-- start autogeneration tags -->
-* `latest, 2.0.60`
-* `2, 2.0, 2.0.55, stable, stable-2.0.55`
-* `2.0.59`
-* `stable-1.1.110, 1, 1.1, 1.1.110`
-* `1.0.0, 1.0`
-* `0.17.79, 0.17`
-* `0.16.51, 0.16`
-* `0.15.40, 0.15`
-* `0.14.23, 0.14`
-* `0.13.20, 0.13`
-* `0.12.35, 0.12`
+* `latest, 2.0.65`
+* `2, 2.0, 2.0.60, stable, stable-2.0.60`
 <!-- end autogeneration tags -->
 
 ## Tag descriptions
@@ -505,6 +496,19 @@ Consider using rootless images if you:
 
 ## Troubleshooting
 
+### Permission Issues
+
+If you're experiencing permission errors such as:
+- `chown: Operation not permitted`
+- `Permission denied [/factorio/saves]`
+- `Util.cpp:81: Operation not permitted`
+- Files owned by unexpected UIDs (like 100844 instead of 845)
+
+Please refer to our comprehensive [Permission Issues Guide](./PERMISSION_ISSUES_GUIDE.md) for detailed solutions. Common fixes include:
+- **Updating Docker** to version 20.x or newer (this resolves many issues)
+- **Using the rootless image** variants (e.g., `factoriotools/factorio:stable-rootless`)
+- **Setting correct ownership** for your specific Docker configuration
+
 ### My server is listed in the server browser, but nobody can connect
 
 Check the logs. If there is the line `Own address is RIGHT IP:WRONG PORT`, then this could be caused by the Docker proxy. If the the IP and port is correct it's probably a port forwarding or firewall issue instead.

buildinfo.json

@@ -1,19 +1,19 @@
 {
-  "2.0.55": {
-    "sha256": "ef12a54d1556ae1f84ff99edc23706d13b7ad41f1c02d74ca1dfadf9448fcbae",
-    "tags": [
-      "stable",
-      "stable-2.0.55",
-      "2",
-      "2.0",
-      "2.0.55"
-    ]
-  },
   "2.0.60": {
     "sha256": "69b5be1a867fd99524f9914dfee900a1ac386cf4e74c4a63768c05dc4d2b2b0b",
     "tags": [
-      "latest",
+      "stable",
+      "stable-2.0.60",
+      "2",
+      "2.0",
       "2.0.60"
     ]
+  },
+  "2.0.65": {
+    "sha256": "6b80f0fbeb43753ed7654695ffa427f442496068f2f72129de76cea246a0c63e",
+    "tags": [
+      "latest",
+      "2.0.65"
+    ]
   }
 }

docker/Dockerfile

@@ -54,8 +54,8 @@ RUN apt-get -q update \
     fi \
     && rm -rf /var/lib/apt/lists/*
 
-RUN addgroup --system --gid "$PGID" "$GROUP" \
-    && adduser --system --uid "$PUID" --gid "$PGID" --no-create-home --disabled-password --shell /bin/sh "$USER"
+RUN groupadd --system --gid "$PGID" "$GROUP" \
+    && useradd --system --uid "$PUID" --gid "$PGID" --no-create-home --shell /bin/sh "$USER"
 
 # version checksum of the archive to download
 ARG VERSION

docker/docker-compose.yml

@@ -6,8 +6,8 @@ services:
       args:
         # Check buildinfo.json for supported versions and SHAs
         # https://github.com/factoriotools/factorio-docker/blob/master/buildinfo.json
-        - VERSION=2.0.55
-        - SHA256=ef12a54d1556ae1f84ff99edc23706d13b7ad41f1c02d74ca1dfadf9448fcbae
+        - VERSION=2.0.60
+        - SHA256=69b5be1a867fd99524f9914dfee900a1ac386cf4e74c4a63768c05dc4d2b2b0b
     ports:
       - "34197:34197/udp"
       - "27015:27015/tcp"

docker/files/docker-entrypoint-rootless.sh

@@ -53,10 +53,9 @@ fi
 # In rootless mode, we don't need to handle user switching or chown
 # The container runs as the specified user from the start
 EXEC=""
-if [[ -f /bin/box64 ]]; then
-  # Use emulator for ARM hosts
-  EXEC="/bin/box64"
-fi
+# Setup ARM64 emulation support
+# shellcheck disable=SC1091
+source "${INSTALLED_DIRECTORY}/setup-exec.sh"
 
 # Update config path
 sed -i '/write-data=/c\write-data=\/factorio/' /opt/factorio/config/config.ini

docker/files/docker-entrypoint.sh

@@ -41,10 +41,10 @@ if [[ $NRTMPSAVES -gt 0 ]]; then
 fi
 
 if [[ ${UPDATE_MODS_ON_START:-} == "true" ]]; then
-  ${INSTALLED_DIRECTORY}/docker-update-mods.sh
+  "${INSTALLED_DIRECTORY}"/docker-update-mods.sh
 fi
 
-${INSTALLED_DIRECTORY}/docker-dlc.sh
+"${INSTALLED_DIRECTORY}"/docker-dlc.sh
 
 EXEC=""
 if [[ $(id -u) == 0 ]]; then
@@ -56,11 +56,10 @@ if [[ $(id -u) == 0 ]]; then
   # Drop to the factorio user
   EXEC="runuser -u factorio -g factorio --"
 fi
-if [[ -f /bin/box64 ]]; then
-  # Use an emulator to run on ARM hosts
-  # this only gets installed when the target docker platform is linux/arm64
-  EXEC="$EXEC /bin/box64"
-fi
+
+# Setup ARM64 emulation support
+# shellcheck disable=SC1091
+source "${INSTALLED_DIRECTORY}/setup-exec.sh"
 
 sed -i '/write-data=/c\write-data=\/factorio/' /opt/factorio/config/config.ini
 

docker/files/scenario.sh

@@ -1,5 +1,6 @@
 #!/bin/bash
 set -eoux pipefail
+INSTALLED_DIRECTORY=$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")
 
 if [[ -z ${1:-} ]]; then
   echo "No argument supplied"
@@ -31,7 +32,12 @@ if [[ ! -f $CONFIG/map-settings.json ]]; then
   cp /opt/factorio/data/map-settings.example.json "$CONFIG/map-settings.json"
 fi
 
-exec /opt/factorio/bin/x64/factorio \
+# Setup ARM64 emulation support
+EXEC=""
+# shellcheck disable=SC1091
+source "${INSTALLED_DIRECTORY}/setup-exec.sh"
+
+exec $EXEC /opt/factorio/bin/x64/factorio \
   --port "$PORT" \
   --start-server-load-scenario "$SERVER_SCENARIO" \
   --preset "$PRESET" \

docker/files/scenario2map.sh

@@ -1,5 +1,6 @@
 #!/bin/bash
 set -eoux pipefail
+INSTALLED_DIRECTORY=$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")
 
 if [[ -z ${1:-} ]]; then
   echo "No argument supplied"
@@ -23,5 +24,10 @@ if [[ ! -f $CONFIG/map-settings.json ]]; then
   cp /opt/factorio/data/map-settings.example.json "$CONFIG/map-settings.json"
 fi
 
-exec /opt/factorio/bin/x64/factorio \
+# Setup ARM64 emulation support
+EXEC=""
+# shellcheck disable=SC1091
+source "${INSTALLED_DIRECTORY}/setup-exec.sh"
+
+exec $EXEC /opt/factorio/bin/x64/factorio \
   --scenario2map "$SERVER_SCENARIO"

docker/files/setup-exec.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Setup EXEC variable for running Factorio with ARM64 emulation support
+# This script handles ARM64 emulation and can be combined with user switching as needed
+
+# If EXEC is not already set, initialize it
+if [[ -z "${EXEC:-}" ]]; then
+  EXEC=""
+fi
+
+if [[ -f /bin/box64 ]]; then
+  # Use an emulator to run on ARM hosts
+  # this only gets installed when the target docker platform is linux/arm64
+  EXEC="$EXEC /bin/box64"
+fi
+
+export EXEC

docker/rcon/main.c

@@ -1,3 +1,4 @@
+#define _GNU_SOURCE
 #include <stdio.h>
 #include <stdint.h>
 #include <stdbool.h>
@@ -107,7 +108,8 @@ char* read_password(const char* conf_dir) {
     fseek(fptr, 0, SEEK_SET);  /* same as rewind(f); */
 
     char *password = malloc(fsize + 1);
-    fread(password, fsize, 1, fptr);
+    size_t bytes_read = fread(password, fsize, 1, fptr);
+    (void)bytes_read; // Suppress unused warning
     fclose(fptr);
 
     password[fsize] = 0;