Installation

imgFlux is a Java application that wraps graphicsmagick into a standalone multi-media processing engine. You can run it entirely inside Docker or install the native toolchain for bespoke builds.

Container-first setup (recommended)

Docker is the fastest way to evaluate imgFlux and mirrors the production deployment model.

1. Install Docker – Version 24 or newer is recommended. Podman works as an alternative as long as it supports multi-stage builds.
2. Pull the image – Use the published container from GitHub Container Registry:

   docker pull ghcr.io/cloud-media-forge/imgFlux:latest

   If you need a custom image (for example to bundle watermarks or presets), see Deployment for building a derivative image.
3. Generate secrets – Generate random secrets for HMAC signing:

   openssl rand -hex 32

4. Start a container – Provide HMAC secrets via environment variables or an env file:

   docker run \
     --rm \
     -p 8080:8080 \
     ghcr.io/cloud-media-forge/imgFlux:latest --help

Continue to Quick Start to run real transformations inside the container.

Native installation (for custom builds)

If you need to extend imgFlux or integrate it directly on a host, install the Java toolchain and graphicsmagick locally.

Supported platforms

imgFlux targets Linux and macOS. It also runs inside containers built from Debian- or Alpine-based images as long as graphicsmagick is available. Windows development is possible through WSL2.

Prerequisites

Installing prerequisites

Debian / Ubuntu

sudo apt-get update
sudo apt-get install -y graphicsmagick graphicsmagick-libmagick-dev-compat openjdk-17-jdk

macOS (Homebrew)

brew install graphicsmagick

Tip: After installing rustup, run rustup default stable and rustup component add rustfmt clippy to match the repository tooling.

Fetching the source

git clone https://github.com/cloud-media-forge/imgFlux.git
cd imgFlux

If you are working from a fork, replace the URL accordingly. The repository uses Git submodules only for documentation assets, so a normal clone is sufficient.

Building from source

Compile the debug binary:

mvn clean package

The executable will be placed in target/release/imgFlux.

Use imgFlux-engine as a library

imgFlux now ships both as an HTTP server and as a reusable Java crate. You can embed the processing engine directly into your application without starting the SpringBoot server:

    @Autowired
    private ImageProcessingService imageProcessingService;
 
    // Download original image from storage
    byte[] originalImageData = objectStorageService.downloadFile(bucketName, imagePath);
 
    // If no processing parameters are specified, return original image directly
    if (width == 0 && height == 0 && quality == 80 && !extent && !trim &&
        ("JPG".equalsIgnoreCase(format) || "JPEG".equalsIgnoreCase(format))) {
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.parseMediaType(getContentType(format)));
        headers.setContentLength(originalImageData.length);
        return new ResponseEntity<>(originalImageData, headers, HttpStatus.OK);
        }
 
    // Use image processing service to process image
    byte[] processedImageData = imageProcessingService.processImage(
        originalImageData, width, height, quality, extent, trim, format);

The same API exposes metadata retrieval through image_info and accepts authenticated, signed paths just like the HTTP interface. Server deployments continue to work unchanged.

Next steps

Whether you chose Docker or a native build, proceed to Quick Start to configure secrets, start the server, and perform your first image transformation.