OctoEverywhere Non-Root Wrapper Image

A Docker wrapper that fixes file permission issues with the official OctoEverywhere image by allowing you to set your own user/group IDs.

What is OctoEverywhere? A service that provides remote access, AI failure detection, and notifications for 3D printers.

The Problem

The official OctoEverywhere image runs as UID 1001, which creates permission conflicts when you mount host directories owned by your user (typically UID 1000).

The Solution

• Runtime user mapping: Set PUID/PGID to match your host user
• Automatic permissions: Fixes /data directory ownership on startup
• Zero maintenance: Stays updated with official releases automatically
• Drop-in replacement: Same usage as official image, just add PUID/PGID

Repository Structure

sibest19/octoeverywhere/
├── Dockerfile               # Extends the official image and installs su-exec
├── entrypoint.sh            # Privilege-dropping wrapper script
├── health-check.sh          # Health monitoring script with alerts
├── test-wrapper.sh          # Comprehensive test suite
└── .github/
    └── workflows/
        ├── build-and-push.yml  # CI/CD pipeline for automated builds
        ├── rollback.yml        # Emergency rollback workflow
        └── health-check.yml    # Automated health monitoring

Usage

Get your user/group IDs first:

echo "PUID=$(id -u) PGID=$(id -g)"

Docker Compose:

services:
  octoeverywhere:
    image: ghcr.io/sibest19/octoeverywhere:latest
    environment:
      - PUID=1000                   # Replace with your user ID
      - PGID=1000                   # Replace with your group ID
      - COMPANION_MODE=elegoo       # Your printer type
      - PRINTER_IP=192.168.1.100    # Your printer's IP
    volumes:
      - ./data:/data
    restart: unless-stopped

Docker CLI:

docker run -d \
  -e PUID=$(id -u) -e PGID=$(id -g) \
  -e COMPANION_MODE=elegoo \
  -e PRINTER_IP=192.168.1.100 \
  -v ./data:/data \
  ghcr.io/sibest19/octoeverywhere:latest

Environment Variables

Variable	Description	Example
PUID	Your user ID (run id -u)	1000
PGID	Your group ID (run id -g)	1000
COMPANION_MODE	Printer type	elegoo, bambu
PRINTER_IP	Printer's network address	192.168.1.100

How It Works

1. Build time: Extracts the official image's startup command
2. Runtime: Creates a user with your PUID/PGID, fixes /data ownership, then runs the original command as that user

This approach automatically adapts to upstream changes.

Automated Builds

GitHub Actions automatically:

• Checks daily for upstream image updates
• Detects significant changes (entrypoint/command modifications) and alerts
• Tests images before promotion using comprehensive test suite
• Only rebuilds when upstream changes to avoid unnecessary churn
• Publishes to ghcr.io/sibest19/octoeverywhere with multiple tags:
  • latest - Current stable version (tested)
  • v<version> - Version-specific tags

Resilience Features

• Pre-deployment testing: All images are tested before being tagged as latest
• Change detection: Alerts when upstream makes significant changes that might break compatibility
• Emergency rollback: Manual workflow to quickly revert to previous version
• Health monitoring: Standalone script for continuous monitoring (health-check.sh)

Emergency Rollback

If something breaks, quickly revert to a previous version:

Option 1: Use a specific version

docker pull ghcr.io/sibest19/octoeverywhere:v1.2.3

Option 2: Automated rollback Go to Actions → Emergency Rollback → Run workflow, then select the target version.

Health Monitoring

Run the included health check script:

./health-check.sh

Set environment variables for alerts:

export TELEGRAM_BOT_TOKEN="your_bot_token"
export TELEGRAM_CHAT_ID="your_chat_id"
./health-check.sh

Testing Changes

Test the wrapper locally:

./test-wrapper.sh ghcr.io/sibest19/octoeverywhere:latest

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b my-feature).
3. Commit your changes and push (git push origin my-feature).
4. Open a Pull Request describing your change.

Please ensure any additions keep the wrapper minimal and continue to leverage the upstream image.

---

Created and maintained by Simone Andreani (@sibest19). Feel free to open issues or PRs for improvements.