Skip to main content

Running oMFT as a Non-Root User

By default, Docker containers run as the root user, which can pose security risks. oMFT fully supports running as a non-root user, which is recommended for production environments.

Benefits of Running as Non-Root​

  • Improved Security: Limits the potential damage if the container is compromised
  • Better File Permissions: Files created by the container will match your host user permissions
  • Compliance: Many security policies and best practices require containers to run as non-root

Methods to Run oMFT as Non-Root​

oMFT supports several methods for running as a non-root user, each with its own advantages.

This method allows changing the user at runtime without rebuilding the image:

# Using current user's ID
docker run -e PUID=$(id -u) -e PGID=$(id -g) ghcr.io/avier99/omft:latest

Or in docker-compose.yml:

services:
  omft:
    image: ghcr.io/avier99/omft:latest
    environment:
      - PUID=1000  # Your user ID
      - PGID=1000  # Your group ID
    volumes:
      - ./data:/app/data
      - ./backups:/app/backups

Method 2: Using the --user Flag with Docker Run​

This method is simple but doesn't support some advanced features like permission fixing:

docker run --user $(id -u):$(id -g) ghcr.io/avier99/omft:latest

Method 3: Using Docker Compose with Environment Variables​

This approach uses environment variables from the host for the user directive:

services:
  omft:
    image: ghcr.io/avier99/omft:latest
    user: "${UID:-1000}:${GID:-1000}"
    volumes:
      - ./data:/app/data
      - ./backups:/app/backups

Run with:

UID=$(id -u) GID=$(id -g) docker-compose up -d

Method 4: Building a Custom Image with Specified UID/GID​

This method builds a custom image with your specified user ID:

FROM ghcr.io/avier99/omft:latest

ARG UID=1000
ARG GID=1000

RUN usermod -u $UID omft && groupmod -g $GID omft

In docker-compose.yml:

services:
  omft:
    build:
      context: .
      args:
        UID: ${UID:-1000}
        GID: ${GID:-1000}

Environment Variables for User Management​

VariableDescriptionDefault
PUIDUser ID to run asBuilt-in user ID (1000)
PGIDGroup ID to run asBuilt-in group ID (1000)
USERNAMEUsername to useomft

Volume Permissions​

When running as a non-root user, ensure that the directories on the host have appropriate permissions for the container user:

# Create directories
mkdir -p data backups

# Set ownership to match the PUID/PGID you'll use
chown -R 1000:1000 data backups

Option 2: Adjust Permissions (Less Secure, but Easier for Testing)​

mkdir -p data backups
chmod -R 777 data backups

Verifying Non-Root Operation​

To verify that oMFT is running as a non-root user:

docker exec omft id

You should see output showing the UID and GID you specified.

Troubleshooting Permission Issues​

Common Issues​

  1. Volume Mount Permission Denied: The container user doesn't have permission to access mounted volumes

    Solution:

    chown -R <PUID>:<PGID> ./data ./backups

  2. Cannot Write to Log Files: Permission issues with log files

    Solution:

    # Ensure log directory exists and has correct permissions
    mkdir -p ./data/logs
    chown -R <PUID>:<PGID> ./data/logs

  3. Database Permission Errors: SQLite database permissions

    Solution:

    # Check and fix database file permissions
    chown <PUID>:<PGID> ./data/gomft.db
    chmod 644 ./data/gomft.db

Checking Container Logs for Permission Issues​

docker logs omft | grep -i "permission denied"

Volume Permission Script​

You can use this script to fix permissions on your data volumes:

#!/bin/bash
# Fix permissions for oMFT volumes

# Set your PUID and PGID here
PUID=1000
PGID=1000

# Create directories if they don't exist
mkdir -p ./data ./backups

# Fix ownership
chown -R $PUID:$PGID ./data ./backups

echo "Permissions fixed for oMFT volumes"

Security Considerations​

When running as non-root, there are still some security considerations:

  • Avoid using chmod 777 in production environments
  • Use volume binding with caution, especially for sensitive data
  • Consider using Docker secrets for sensitive credentials
  • Regularly update your oMFT image to get the latest security fixes
  • Implement network segmentation to limit the container's access

Example: Complete Docker Compose Setup with Non-Root User​

version: '3.8'

services:
  omft:
    image: ghcr.io/avier99/omft:latest
    container_name: omft
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - BASE_URL=http://localhost:8080
    volumes:
      - ./data:/app/data
      - ./backups:/app/backups
    ports:
      - "8080:8080"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 1m
      timeout: 10s
      retries: 3
      start_period: 30s

Best Practices Summary​

  1. Always run oMFT as a non-root user in production
  2. Use PUID/PGID environment variables for flexible user mapping
  3. Set appropriate permissions on volume mounts
  4. Verify the container is running as the expected user
  5. Follow least privilege principles for the container user