Add security hardening for Podman/Docker compatibility with non-root user

Co-authored-by: thawn <1308449+thawn@users.noreply.github.com>

Author: Copilot

build/docker/Dockerfile

@@ -35,15 +35,31 @@ COPY . /app/
 # For production builds with proper certificate setup, these flags can be removed.
 RUN pip install --no-cache-dir --trusted-host pypi.org --trusted-host files.pythonhosted.org -e .
 
+# Create a non-root user for running the application
+# Using UID/GID 1000 which is common for the first user on most Linux systems
+# This allows for better compatibility with Podman's user namespace mapping
+RUN groupadd -g 1000 ttmp32gme && \
+    useradd -r -u 1000 -g ttmp32gme -m -d /home/ttmp32gme -s /bin/bash ttmp32gme
+
 # Set up directories and copy config
+# Use proper permissions instead of 777 for security
 ENV APPDATA=/var/lib/
 RUN mkdir -p ${APPDATA}/ttmp32gme/library /mnt/tiptoi && \
     cp /app/src/ttmp32gme/config.sqlite ${APPDATA}/ttmp32gme/ && \
-    chmod -R 777 ${APPDATA}/ttmp32gme/library
+    chown -R ttmp32gme:ttmp32gme ${APPDATA}/ttmp32gme /mnt/tiptoi && \
+    chmod -R 775 ${APPDATA}/ttmp32gme && \
+    chmod 664 ${APPDATA}/ttmp32gme/config.sqlite
+
+# Declare volumes for persistent data
+# This helps Podman/Docker users understand which directories should be mounted
+VOLUME ["${APPDATA}/ttmp32gme", "/mnt/tiptoi"]
 
 # Expose port 8080
 EXPOSE 8080
 
+# Switch to non-root user
+USER ttmp32gme
+
 # Run the Python backend
 CMD ["python", "-m", "ttmp32gme.ttmp32gme", "--host=0.0.0.0", "--port=8080", "--database=/var/lib/ttmp32gme/config.sqlite", "--library=/var/lib/ttmp32gme/library"]
 

build/docker/README.md

@@ -1,15 +1,144 @@
-A docker image for ttmp32gme.
+# ttmp32gme Docker/Podman Container
 
-Set the environment variable `HOST=0.0.0.0` to make ttmp32gme accessible to other computers in your network.
+A containerized version of ttmp32gme that converts MP3/audio files into TipToi GME files.
 
+## Features
+
+- **Security**: Runs as non-root user (UID/GID 1000)
+- **Podman Compatible**: Works seamlessly with Podman's user namespace mapping
+- **Persistent Storage**: Separate volumes for configuration and TipToi device
+
+## Quick Start
+
+### Using Docker
+
+```bash
+docker run -d \
+  --rm \
+  --name ttmp32gme \
+  --publish 8080:8080 \
+  --volume ttmp32gme-data:/var/lib/ttmp32gme \
+  --volume /path/to/tiptoi:/mnt/tiptoi \
+  thawn/ttmp32gme:latest
+```
+
+### Using Podman
+
+```bash
+podman run -d \
+  --rm \
+  --name ttmp32gme \
+  --publish 8080:8080 \
+  --volume ttmp32gme-data:/var/lib/ttmp32gme \
+  --volume /path/to/tiptoi:/mnt/tiptoi:Z \
+  thawn/ttmp32gme:latest
+```
+
+**Note for Podman users**: The `:Z` flag on the TipToi volume enables proper SELinux labeling for shared access.
+
+## Volume Mounts
+
+- **`/var/lib/ttmp32gme`**: Application data (database, generated library files)
+  - First run: Container initializes this directory with default config
+  - Subsequent runs: Uses existing data for persistence
+  
+- **`/mnt/tiptoi`**: TipToi pen mount point
+  - Mount your TipToi device here to directly write generated files
+
+## User Permissions
+
+The container runs as user `ttmp32gme` (UID 1000, GID 1000). 
+
+### For Podman Users
+
+Podman automatically maps the container user to your host user, so permissions work seamlessly:
+
+```bash
+# Your files will be owned by your user on the host
+podman run --rm \
+  --volume ./my-data:/var/lib/ttmp32gme \
+  --volume /media/tiptoi:/mnt/tiptoi:Z \
+  --publish 8080:8080 \
+  thawn/ttmp32gme:latest
 ```
+
+### For Docker Users
+
+If you encounter permission issues, you can use these options:
+
+1. **Option 1**: Match your user ID (recommended)
+```bash
+docker run --user $(id -u):$(id -g) \
+  --volume ./my-data:/var/lib/ttmp32gme \
+  --volume /media/tiptoi:/mnt/tiptoi \
+  --publish 8080:8080 \
+  thawn/ttmp32gme:latest
+```
+
+2. **Option 2**: Adjust host directory permissions
+```bash
+sudo chown -R 1000:1000 ./my-data
+```
+
+## Accessing the Application
+
+Once running, open your web browser to:
+- **Local access**: http://localhost:8080
+- **Network access**: http://your-server-ip:8080
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| HOST | 0.0.0.0 | Server bind address |
+| PORT | 8080 | Server port |
+
+Example with custom settings:
+
+```bash
 docker run -d \
-	--rm \
-	--publish 8080:8080 \
-	--volume ${ttmp32gmeStorage}:/var/lib/ttmp32gme \
-	--volume </path/to/tiptoi:/mnt/tiptoi \
-	-env HOST=127.0.0.1 \
-	-env PORT=8080 \
-	--name ttmp32gme \
-	thawn/ttmp32gme:latest
+  --env HOST=127.0.0.1 \
+  --env PORT=9000 \
+  --publish 9000:9000 \
+  --volume ttmp32gme-data:/var/lib/ttmp32gme \
+  thawn/ttmp32gme:latest
+```
+
+## Security Features
+
+This container implements security best practices:
+
+- ✅ **Non-root user**: Runs as dedicated `ttmp32gme` user
+- ✅ **Minimal permissions**: Files owned by user with 775/664 permissions
+- ✅ **Explicit volumes**: Declared volume mount points
+- ✅ **Health checks**: Automatic container health monitoring
+- ✅ **Podman ready**: Full compatibility with Podman's rootless mode
+
+## Troubleshooting
+
+### Permission denied errors
+
+If you get "permission denied" errors when accessing volumes:
+
+**For Podman**:
+```bash
+# Add :Z flag for SELinux systems
+podman run --volume /path/to/data:/var/lib/ttmp32gme:Z ...
+```
+
+**For Docker**:
+```bash
+# Match your user ID
+docker run --user $(id -u):$(id -g) ...
+```
+
+### Cannot write to TipToi device
+
+Ensure your TipToi device is mounted with write permissions:
+```bash
+# Check current permissions
+ls -la /media/tiptoi
+
+# If needed, adjust permissions
+sudo chmod 775 /media/tiptoi
 ```