mirror/factorio-docker
1
0
Fork 0
mirror of https://github.com/factoriotools/factorio-docker.git synced 2025-07-12 20:15:35 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Consolidate rootless documentation and mark as experimental

Browse Source 
- Remove separate README-ROOTLESS.md file
- Integrate rootless documentation into main README.md
- Mark rootless support as experimental
- Add clear documentation about limitations and use cases
- Include warning about experimental nature

This consolidates all documentation in one place and makes it clear
that rootless support is still experimental.

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Florian Kinder
2025-07-12 13:44:28 +09:00
parent 44e651a3a6
commit 708e9526ef
2 changed files with 27 additions and 144 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
README-ROOTLESS.md
View File

@ -1,139 +0,0 @@
# Rootless Docker Support
This document describes the rootless Docker images for Factorio, which are designed to work better with rootless Docker installations and avoid permission issues.
## What is Rootless Docker?
Rootless Docker allows running the Docker daemon and containers as a non-root user, which improves security by eliminating the need for root privileges. However, it introduces complexity with UID/GID mapping that can cause permission issues with volumes.
## Rootless Image Tags
For each regular Factorio image tag, there's a corresponding rootless tag with the `-rootless` suffix:
- `latest` → `latest-rootless`
- `stable` → `stable-rootless`
- `2.0.55` → `2.0.55-rootless`
- etc.
## Key Differences from Regular Images
1. **No dynamic UID/GID mapping**: The rootless images run as UID 1000 by default and don't support PUID/PGID environment variables
2. **No runtime chown operations**: Eliminates the recursive chown that can cause race conditions
3. **Simplified permissions**: All directories are created with open permissions (777) during build
4. **USER directive**: The container runs as non-root from the start
## Usage
### Basic Usage
```bash
docker run -d \
-p 34197:34197/udp \
-p 27015:27015/tcp \
-v /opt/factorio:/factorio \
--name factorio \
factoriotools/factorio:stable-rootless
```
### With Rootless Docker
If you're running rootless Docker, the container will work out of the box:
```bash
# As your regular user (not root)
docker run -d \
-p 34197:34197/udp \
-p 27015:27015/tcp \
-v ~/factorio:/factorio \
--name factorio \
factoriotools/factorio:stable-rootless
```
### With Regular Docker
If you're running regular Docker but want to avoid permission issues:
```bash
# Pre-create the volume directory with your user's permissions
mkdir -p /opt/factorio
sudo chown -R $(id -u):$(id -g) /opt/factorio
# Run the container
docker run -d \
--user $(id -u):$(id -g) \
-p 34197:34197/udp \
-p 27015:27015/tcp \
-v /opt/factorio:/factorio \
--name factorio \
factoriotools/factorio:stable-rootless
```
## Environment Variables
All the same environment variables from the regular image are supported, except:
- `PUID` - Not supported (container runs as UID 1000)
- `PGID` - Not supported (container runs as GID 1000)
## Migrating from Regular Images
If you're switching from a regular image to a rootless image:
1. Stop your existing container
2. Fix permissions on your volume (one time only):
```bash
sudo chown -R 1000:1000 /opt/factorio
# Or if you want to match your user:
sudo chown -R $(id -u):$(id -g) /opt/factorio
```
3. Start the new rootless container
## Troubleshooting
### Permission Denied Errors
If you get permission errors, ensure your volume directory is writable by UID 1000 or your user:
```bash
# Check current ownership
ls -la /opt/factorio
# Fix ownership for UID 1000 (default)
sudo chown -R 1000:1000 /opt/factorio
# Or fix for your current user
sudo chown -R $(id -u):$(id -g) /opt/factorio
```
### Running as a Different User
If you need to run as a different UID, override it at runtime:
```bash
docker run -d \
--user 2000:2000 \
-v /opt/factorio:/factorio \
factoriotools/factorio:stable-rootless
```
## Building Rootless Images
To build rootless images locally:
```bash
# Build rootless images for current architecture
python3 build.py --rootless
# Build and push multi-arch rootless images
python3 build.py --rootless --multiarch --push-tags
# Build both regular and rootless images
python3 build.py --both --multiarch --push-tags
```
## Why Use Rootless Images?
1. **Avoid permission issues**: No more files with unexpected ownership
2. **Better security**: Runs as non-root by default
3. **Simpler**: No complex permission logic at startup
4. **Faster startup**: No recursive chown operations
5. **Rootless Docker compatible**: Works seamlessly with rootless Docker installations

32
README.md
View File

@ -439,16 +439,26 @@ stream {
If your factorio host uses multiple IP addresses (very common with IPv6), you might additionally need to bind Factorio to a single IP (otherwise the UDP proxy might get confused with IP mismatches). To do that pass the `BIND` envvar to the container: `docker run --network=host -e BIND=2a02:1234::5678 ...` If your factorio host uses multiple IP addresses (very common with IPv6), you might additionally need to bind Factorio to a single IP (otherwise the UDP proxy might get confused with IP mismatches). To do that pass the `BIND` envvar to the container: `docker run --network=host -e BIND=2a02:1234::5678 ...`
## Rootless Docker Support ## Rootless Docker Support (Experimental)
> **Note**: Rootless support is currently experimental. Please report any issues you encounter.
If you're experiencing permission issues or want better security, consider using the rootless images. These images are designed to work seamlessly with rootless Docker installations and avoid common permission problems. If you're experiencing permission issues or want better security, consider using the rootless images. These images are designed to work seamlessly with rootless Docker installations and avoid common permission problems.
### What are Rootless Images?
The rootless images differ from regular images in several ways:
- Run as UID 1000 (non-root) by default
- No dynamic UID/GID mapping (PUID/PGID not supported)
- No runtime chown operations
- All directories created with open permissions during build
### Rootless Image Tags ### Rootless Image Tags
Each regular tag has a corresponding rootless version with the `-rootless` suffix: Each regular tag has a corresponding rootless version with the `-rootless` suffix:
- `latest-rootless` - `latest-rootless` (experimental)
- `stable-rootless` - `stable-rootless` (experimental)
- `2.0.55-rootless` - `2.0.55-rootless` (experimental)
### Quick Start with Rootless ### Quick Start with Rootless
@ -468,7 +478,19 @@ Key differences:
- Runs as UID 1000 by default - Runs as UID 1000 by default
- No permission issues with volumes - No permission issues with volumes
For more information, see the [Rootless Docker documentation](README-ROOTLESS.md). ### When to Use Rootless Images
Consider using rootless images if you:
- Are running Docker in rootless mode
- Experience permission issues with volume mounts
- Want to avoid containers running as root
- Don't need dynamic UID/GID mapping via PUID/PGID
### Limitations
- PUID/PGID environment variables are not supported
- Fixed to UID 1000 (may not match your host user)
- Experimental feature - may have undiscovered issues
## Troubleshooting ## Troubleshooting