Automated Deployment

This directory contains automated deployment scripts that will get imgFlux up and running on a fresh Linux machine with minimal effort.

Available Scripts

Docker Deployment

deploy.sh - Deploy imgFlux using Docker Compose
uninstall.sh - Remove Docker-based deployment

Systemd Deployment

deploy-systemd.sh - Deploy imgFlux as a native systemd service
upgrade-systemd.sh - Upgrade imgFlux to the latest version
uninstall-systemd.sh - Remove systemd-based deployment

Deployment Options

Choose the deployment method that best fits your infrastructure:

Option 1: Docker Deployment (Recommended)

Uses Docker and Docker Compose for containerized deployment. Simplest and most portable.

Option 2: Systemd Deployment

Installs imgFlux as a native systemd service. Best for environments where Docker is not available or not desired.

Docker Deployment (Option 1)

Quick Start

Run the deployment script:

curl -fsSL https://raw.githubusercontent.com/cloud-media-forge/imgFlux/main/deployment/deploy.sh | bash

Or download and run locally:

wget https://raw.githubusercontent.com/cloud-media-forge/imgFlux/main/deployment/deploy.sh
chmod +x deploy.sh
./deploy.sh

What the Docker Script Does

The Docker deployment script will:

Check Prerequisites
- Verify Docker installation
- Install Docker automatically if not present
- Check for available ports
- Validate system requirements
Interactive Configuration
- Ask you to choose a caching strategy (Memory, Disk, Hybrid, or None)
- Ask if you want to enable Prometheus + Grafana monitoring
Automated Setup
- Pull the latest imgFlux Docker image from ghcr.io/cloud-media-forge/imgFlux:latest
- Generate secure random keys for HMAC signing
- Create configuration files with sane defaults
- Set up monitoring stack (if enabled)
- Download pre-built Grafana dashboard
- Start all services using Docker Compose
Health Checks
- Verify services are running correctly
- Check imgFlux responds to status endpoint
- Display access URLs and credentials

What's NOT Included (User Responsibility)

HTTPS/TLS termination (use reverse proxy)
Firewall configuration
Rate limiting at proxy level
Bearer token authentication
Network isolation
Backup automation

Configuration Options

Cache Types

The script offers four caching strategies:

Type	Description	Default Capacity	Persistence
Memory	Fast in-memory cache	1000 entries	No
Disk	File-based persistent cache	2 GB	Yes
Hybrid	Memory + Disk combined	1000 + 2 GB	Partial
None	No caching	-	-

Monitoring

If enabled, the script deploys:

Service	Port	Credentials	Purpose
imgFlux	3000	-	Image processing API
Metrics	9000	-	Prometheus metrics
Prometheus	9090	-	Metrics storage/queries
Grafana	3001	admin/admin	Visualization dashboards

Default Configuration

The script creates a deployment with these defaults:

# Port Configuration
IMGFLUX_PORT=3000          # Main HTTP service
PROMETHEUS_PORT=9090        # Prometheus UI (if enabled)
GRAFANA_PORT=3001           # Grafana UI (if enabled)
METRICS_PORT=9000           # Metrics endpoint (if enabled)
 
# Logging
IMGFLUX_LOG_LEVEL=info
 
# Timeouts
IMGFLUX_TIMEOUT=30
IMGFLUX_DOWNLOAD_TIMEOUT=10
 
# Security (generated automatically)
IMGFLUX_KEY=<random_128_char_hex>
IMGFLUX_SALT=<random_128_char_hex>

Deployment Location

All configuration files are stored in ~/.imgFlux/:

~/.imgFlux/
├── .env                            # Environment variables
├── docker-compose.yml              # Docker Compose configuration
├── prometheus/
│   └── prometheus.yml              # Prometheus scrape config
├── grafana-dashboards/
│   ├── dashboard-provisioning.yml  # Dashboard auto-provisioning config
│   └── imgFlux-dashboard.json     # Pre-built imgFlux dashboard
└── grafana-datasources.yml         # Grafana Prometheus datasource

Error Handling

The script checks for common issues:

Port conflicts - Validates all required ports are available
Docker installation - Installs Docker if missing
Docker daemon - Starts Docker if not running
Image pull failures - Reports network/registry issues
Service startup failures - Shows logs for debugging

Post-Deployment

After successful deployment:

Test the service:
curl http://localhost:3000/status
View logs:
docker logs imgFlux -f
Access monitoring (if enabled):
- Prometheus: http://localhost:9090
- Grafana: http://localhost:3001 (admin/admin)
  - The imgFlux dashboard is automatically provisioned and ready to use
  - Look for "imgFlux Monitoring Dashboard" in the dashboard list

Manage the service:

cd ~/.imgFlux
 
# Restart services
docker compose restart
 
# Stop services
docker compose down
 
# Update to latest version
docker compose pull
docker compose up -d
 
# View all logs
docker compose logs -f

Security Considerations

⚠️ Important Security Notes:

HMAC Keys: The script generates secure random keys stored in ~/.imgFlux/.env. Keep this file secure!
Signed URLs: By default, imgFlux requires HMAC-signed URLs for security. Use the generated IMGFLUX_KEY and IMGFLUX_SALT in the .env to make signatures.
Grafana Password: If monitoring is enabled, change the default Grafana password (admin/admin) immediately after the first login.
Production Deployment: For production use, consider:
- Using HTTPS with a reverse proxy (nginx, Caddy, Traefik)
- Setting up firewall rules
- Implementing rate limiting at the proxy level
- Backing up the .env file securely
- Using Docker secrets or environment variable management

Manual Configuration

To customize the deployment, edit the generated files:

cd ~/.imgFlux
 
# Edit environment variables
nano .env
 
# Edit Docker Compose configuration
nano docker-compose.yml
 
# Apply changes
docker compose up -d

Common Customizations

Change the port:

# In .env
IMGFLUX_BIND=8080
 
# In docker-compose.yml, update the ports section

Add rate limiting:

# In .env
IMGFLUX_RATE_LIMIT_PER_MINUTE=100

Increase cache size:

# In .env
IMGFLUX_CACHE_MEMORY_CAPACITY=5000
IMGFLUX_CACHE_DISK_CAPACITY=53687091200  # 50 GB (default 2 GB)

Enable unsigned URLs (NOT RECOMMENDED for production):

# In .env
IMGFLUX_ALLOW_UNSIGNED=true

Troubleshooting

Service won't start

# Check logs
docker logs imgFlux
 
# Check if ports are in use
sudo lsof -i :3000
 
# Verify Docker is running
docker ps

Can't pull Docker image

# Test connectivity to GitHub Container Registry
docker pull ghcr.io/cloud-media-forge/imgFlux:latest
 
# If behind a proxy, configure Docker proxy settings

Cache not working

# Check cache configuration in .env
cat ~/.imgFlux/.env | grep CACHE
 
# For disk cache, verify directory permissions
ls -la /var/imgFlux/cache
 
# Check metrics
curl http://localhost:9000/metrics | grep cache

Monitoring not showing data

# Check Prometheus targets
curl http://localhost:9090/targets
 
# Verify imgFlux metrics endpoint
curl http://localhost:9000/metrics
 
# Check Grafana logs
docker logs imgFlux-grafana

Uninstalling

Automated Uninstall

Use the provided uninstall script for easy removal:

cd ~/.imgFlux
curl -fsSL https://raw.githubusercontent.com/cloud-media-forge/imgFlux/main/deployment/uninstall.sh | bash

Or if you have the script locally:

./uninstall.sh

The script will:

Stop and remove all imgFlux containers
Remove Docker volumes
Remove configuration files
Remove cache directories
Optionally remove Docker images

Manual Uninstall

To manually remove imgFlux:

# Stop and remove containers
cd ~/.imgFlux
docker compose down -v
 
# Remove deployment files
rm -rf ~/.imgFlux
 
# Remove cache directory (if using disk cache)
sudo rm -rf /var/imgFlux
 
# Remove Docker images (optional)
docker rmi ghcr.io/cloud-media-forge/imgFlux:latest
docker rmi prom/prometheus:latest
docker rmi grafana/grafana:latest

Docker Requirements

Linux distribution (Ubuntu, Debian, CentOS, RHEL, etc.)
2 GB RAM minimum (4 GB recommended)
2 GB free disk space (for caching)
Internet connection (for Docker image download)
curl or wget (for running the script)

For environments where Docker is not available or you prefer native system services, use the systemd deployment method. This downloads pre-compiled imgFlux binaries and installs them as a systemd service.

Quick Start

Run the systemd deployment script:

curl -fsSL https://raw.githubusercontent.com/cloud-media-forge/imgFlux/main/deployment/deploy-systemd.sh | bash

Or download and run locally:

wget https://raw.githubusercontent.com/cloud-media-forge/imgFlux/main/deployment/deploy-systemd.sh
chmod +x deploy-systemd.sh
./deploy-systemd.sh

What the Systemd Script Does

The systemd deployment script will:

Check Prerequisites and Install Dependencies
- Detect your Linux distribution and package manager
- Install essential tools (curl, wget, ca-certificates)
- Install graphicsmagick (required for image processing)
- Verify all required ports are available
Download imgFlux Binary
- Fetch the latest release information from GitHub
- Detect system architecture (amd64 or arm64)
- Download the pre-compiled binary for your architecture
- Extract and install the binary to /opt/imgFlux/
Interactive Configuration
- Ask you to choose a caching strategy (Memory, Disk, Hybrid, or None)
- Ask if you want to enable Prometheus + Grafana monitoring
System Setup
- Create systemd service files for imgFlux
- Generate secure random keys for HMAC signing
- Create configuration files with sane defaults
- Set up proper directory structure and permissions
- Install and configure Prometheus (if monitoring enabled)
- Install and configure Grafana (if monitoring enabled)
Service Management
- Enable services to start on boot
- Start all services
- Perform health checks
- Display access URLs and credentials

System Locations

The systemd deployment uses standard Linux filesystem locations:

/opt/imgFlux/               # Binary installation
├── imgFlux                 # Main executable

/etc/imgFlux/               # Configuration
├── imgFlux.env             # Environment variables and keys

/var/lib/imgFlux/           # Data and state
├── cache/                   # Disk cache (if enabled)
├── prometheus/              # Prometheus data (if enabled)
└── grafana/                 # Grafana data (if enabled)

/var/log/imgFlux/           # Logs
├── imgFlux.log             # Application logs
└── imgFlux-error.log       # Error logs

~/.imgFlux/                 # User backup
└── imgFlux.env.backup      # Configuration backup

Service Management

After deployment, manage imgFlux using standard systemd commands:

# Start imgFlux
sudo systemctl start imgFlux
 
# Stop imgFlux
sudo systemctl stop imgFlux
 
# Restart imgFlux
sudo systemctl restart imgFlux
 
# Check status
sudo systemctl status imgFlux
 
# View logs (live)
sudo journalctl -u imgFlux -f
 
# View last 100 log lines
sudo journalctl -u imgFlux -n 100
 
# Enable auto-start on boot (enabled by default)
sudo systemctl enable imgFlux
 
# Disable auto-start
sudo systemctl disable imgFlux

If monitoring is enabled:

# Manage Prometheus
sudo systemctl start/stop/restart prometheus
sudo journalctl -u prometheus -f
 
# Manage Grafana
sudo systemctl start/stop/restart grafana-server
sudo journalctl -u grafana-server -f

Configuration Changes

To modify the configuration after deployment:

Edit the environment file:
sudo nano /etc/imgFlux/imgFlux.env
Restart the service to apply changes:
sudo systemctl restart imgFlux

Common Configuration Changes

Change the port:

# In /etc/imgFlux/imgFlux.env
IMGFLUX_BIND=8080
 
# Restart the service
sudo systemctl restart imgFlux

Add rate limiting:

# In /etc/imgFlux/imgFlux.env
IMGFLUX_RATE_LIMIT_PER_MINUTE=100
 
# Restart the service
sudo systemctl restart imgFlux

Increase cache size:

# In /etc/imgFlux/imgFlux.env
IMGFLUX_CACHE_MEMORY_CAPACITY=5000
IMGFLUX_CACHE_DISK_CAPACITY=53687091200  # 50 GB (default 2 GB)
 
# Restart the service
sudo systemctl restart imgFlux

Enable unsigned URLs (NOT RECOMMENDED for production):

# In /etc/imgFlux/imgFlux.env
IMGFLUX_ALLOW_UNSIGNED=true
 
# Restart the service
sudo systemctl restart imgFlux

Updating imgFlux

Automated Upgrade (Recommended)

Use the provided upgrade script for safe, automated updates with automatic rollback on failure:

curl -fsSL https://raw.githubusercontent.com/cloud-media-forge/imgFlux/main/deployment/upgrade-systemd.sh | bash

Or if you have the script locally:

cd /path/to/deployment
./upgrade-systemd.sh

The upgrade script will:

Check for available updates
Create a backup of the current binary
Download and install the latest version
Verify the service starts correctly
Perform health checks
Automatically rollback if anything fails

Manual Upgrade

To manually update to the latest version:

# Stop the service
sudo systemctl stop imgFlux
 
# Download the latest version
cd /tmp
LATEST_VERSION=$(curl -s https://github.com/cloud-media-forge/imgFlux/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
ARCH=$(uname -m)
 
# Determine architecture
if [ "$ARCH" = "x86_64" ]; then
    BINARY_ARCH="amd64"
elif [ "$ARCH" = "aarch64" ] || [ "$ARCH" = "arm64" ]; then
    BINARY_ARCH="arm64"
fi
 
# Download and extract
curl -L -o imgFlux.tar.gz "https://github.com/cloud-media-forge/imgFlux/releases/download/${LATEST_VERSION}/imgFlux-linux-${BINARY_ARCH}.tar.gz"
tar xzf imgFlux.tar.gz
 
# Backup current binary (optional but recommended)
sudo cp /opt/imgFlux/imgFlux /opt/imgFlux/imgFlux.backup
 
# Replace the binary
sudo cp imgFlux /opt/imgFlux/imgFlux
sudo chmod +x /opt/imgFlux/imgFlux
 
# Cleanup
rm -f imgFlux imgFlux.tar.gz
 
# Start the service
sudo systemctl start imgFlux
 
# Verify
sudo systemctl status imgFlux
curl http://localhost:3000/status

Monitoring Setup

When monitoring is enabled, the script:

Installs Prometheus
- Downloads and installs the latest Prometheus binary
- Configures it to scrape metrics from imgFlux
- Sets up as a systemd service
- Accessible at http://localhost:9090
Installs Grafana
- Installs via official repository (apt/yum/dnf)
- Falls back to binary installation if needed
- Configures Prometheus as datasource
- Attempts to download the imgFlux dashboard
- Accessible at http://localhost:3001 (admin/admin)

Troubleshooting

Service won't start

# Check service status
sudo systemctl status imgFlux
 
# View detailed logs
sudo journalctl -u imgFlux -n 100 --no-pager
 
# Check configuration
cat /etc/imgFlux/imgFlux.env
 
# Verify binary exists and is executable
ls -la /opt/imgFlux/imgFlux
 
# Test binary manually
sudo -u $USER /opt/imgFlux/imgFlux

Port already in use

# Check what's using the port
sudo lsof -i :3000
 
# Or use netstat
sudo netstat -tulpn | grep :3000
 
# Change port in configuration
sudo nano /etc/imgFlux/imgFlux.env
# Update IMGFLUX_BIND=3000 to a different port
 
sudo systemctl restart imgFlux

Download or installation failures

# Ensure graphicsmagick is installed
vips --version
 
# Install graphicsmagick manually if needed
# Ubuntu/Debian:
sudo apt-get install graphicsmagick
 
# RHEL/CentOS/Fedora:
sudo dnf install vips
 
# Check internet connectivity
curl -I https://github.com
 
# Verify architecture is supported (should be x86_64 or aarch64)
uname -m
 
# Try downloading manually
LATEST_VERSION=$(curl -s https://github.com/cloud-media-forge/imgFlux/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
echo "Latest version: $LATEST_VERSION"
 
# Check available releases
curl -s https://github.com/cloud-media-forge/imgFlux/releases/latest | grep browser_download_url

Cache not working

# Check cache configuration
grep CACHE /etc/imgFlux/imgFlux.env
 
# For disk cache, verify directory exists and has correct permissions
ls -la /var/lib/imgFlux/cache
 
# Check metrics to see cache stats
curl http://localhost:9000/metrics | grep cache

Monitoring not showing data

# Check Prometheus is running and scraping
sudo systemctl status prometheus
curl http://localhost:9090/targets
 
# Verify imgFlux metrics endpoint
curl http://localhost:9000/metrics
 
# Check Grafana
sudo systemctl status grafana-server
curl http://localhost:3001

Uninstalling

Use the provided uninstall script for systemd deployments:

curl -fsSL https://raw.githubusercontent.com/cloud-media-forge/imgFlux/main/deployment/uninstall-systemd.sh | bash

Or if you have it locally:

./uninstall-systemd.sh

The script will:

Stop and disable all services
Remove systemd service files
Remove binaries
Optionally remove configuration files
Optionally remove data and cache
Optionally uninstall Grafana package

Manual Uninstall

To manually remove imgFlux:

# Stop and disable services
sudo systemctl stop imgFlux prometheus grafana-server
sudo systemctl disable imgFlux prometheus grafana-server
 
# Remove service files
sudo rm /etc/systemd/system/imgFlux.service
sudo rm /etc/systemd/system/prometheus.service
sudo systemctl daemon-reload
 
# Remove binaries
sudo rm -rf /opt/imgFlux
sudo rm /usr/local/bin/prometheus
sudo rm /usr/local/bin/promtool
 
# Remove configuration
sudo rm -rf /etc/imgFlux
sudo rm -rf /etc/prometheus
 
# Remove data (be careful - this removes cache and logs!)
sudo rm -rf /var/lib/imgFlux
sudo rm -rf /var/log/imgFlux
 
# Remove user backup
rm -rf ~/.imgFlux
 
# Optionally remove Grafana
# Ubuntu/Debian:
sudo apt-get remove grafana
 
# RHEL/CentOS/Fedora:
sudo dnf remove grafana

Systemd Requirements

Linux distribution with systemd (Ubuntu 16.04+, Debian 8+, CentOS 7+, RHEL 7+, Fedora, etc.)
Architecture: x86_64 (amd64) or aarch64/arm64
2 GB RAM minimum (4 GB recommended)
2 GB free disk space minimum (for caching and monitoring data)
Internet connection (for downloading binaries and dependencies)
curl or wget (for running the script)
Sufficient privileges to use sudo
graphicsmagick will be installed automatically

Comparison: Docker vs Systemd

Feature	Docker Deployment	Systemd Deployment
Installation Time	Fast (~2-5 minutes)	Fast (~3-7 minutes)
Disk Space	~500 MB (images)	~100 MB (binary + libs)
Dependencies	Docker only	graphicsmagick only
Updates	`docker compose pull`	Download new binary
Isolation	Container isolation	System process
Portability	High (same image everywhere)	Medium (compiled per system)
Resource Overhead	Small (container overhead)	None (native process)
Log Management	Docker logs	systemd journald
Service Management	docker compose	systemctl
Best For	Quick deployment, container infrastructure	Bare metal, no Docker environments

Automated Deployment

On this page