mirror of
https://github.com/factoriotools/factorio-docker.git
synced 2025-07-13 04:25:22 +02:00
7e59315e3d
Implements #547 - Add support for rootless Docker images to avoid permission issues. Key changes: - Add Dockerfile.rootless that runs as UID 1000 by default - Create simplified entrypoint script without chown operations - Add build-rootless.py to build rootless variants with -rootless suffix - Document rootless usage in README-ROOTLESS.md - Update main README with rootless section The rootless images eliminate common permission problems by: - Running as non-root from the start (USER 1000:1000) - Avoiding recursive chown operations that can cause race conditions - Using open permissions (777) on directories during build - Not supporting PUID/PGID environment variables This provides a cleaner solution for rootless Docker users and those experiencing permission issues with volumes. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
136 lines
3.7 KiB
Markdown
136 lines
3.7 KiB
Markdown
# 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 for current architecture
|
|
python3 build-rootless.py
|
|
|
|
# Build and push multi-arch images
|
|
python3 build-rootless.py --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 |