Getting Started Development Help & Support

Installation & Setup

Install ImgCompress with Docker or Docker Compose in under 60 seconds. Run private image compression and conversion on a server, NAS, homelab, or desktop.

Get StartedDocker

Prerequisites#

You only need Docker installed. No other dependencies required.

Install#

Choose the method that works best for you.

Use Docker Compose if you want imgcompress to stay running on your server or NAS.

Create a docker-compose.yml file and paste the following:

yaml
services:
    imgcompress:
        image: karimz1/imgcompress:latest
        container_name: imgcompress
        restart: always
        ports:
        - "3001:5000"
        environment:
        # Set to true for a minimal, mascot-free UI
        - DISABLE_LOGO=false
        # Set to true to hide storage management from your users
        - DISABLE_STORAGE_MANAGEMENT=false

Pull the latest image, then start the container:

bash
docker compose pull
docker compose up -d

💡Why docker compose pull first?

If you've installed imgcompress before, Docker may still have an older image cached locally. docker compose pull makes sure you're running the latest version.

Open your browser at http://localhost:3001.

ℹ️Going to production?

The file above is intentionally minimal. For permanent deployments the repository ships two hardened variants — log rotation, healthchecks, graceful shutdown and TLS.

Variant	Best for	Adds
`advanced.docker-compose.yaml`	Home / LAN	Hardened defaults, reachable from every device on your network.
`proxied.docker-compose.yaml`	Domain + HTTPS	Traefik reverse proxy, automatic Let's Encrypt certificates, security headers.

Both are configured through a .env file and documented in the folder's README.

Browse the compose variants

Default UI (with mascot)

The standard interface includes Captain Compress, the product mascot.

ImgCompress default web UI with Captain Compress mascot ImgCompress default web UI with Captain Compress mascot

Minimal UI (set DISABLE_LOGO=true)

A clean, mascot-free interface ideal for professional, shared, or corporate environments.

ImgCompress minimal web UI without mascot, DISABLE_LOGO=true ImgCompress minimal web UI without mascot, DISABLE_LOGO=true

Try imgcompress instantly with a single command.

First, pull the latest image so you don't run an old cached version:

bash
docker pull karimz1/imgcompress:latest

Default UI (with mascot)

bash
docker run -d --name imgcompress -p 3001:5000 karimz1/imgcompress:latest

ImgCompress default web UI with Captain Compress mascot ImgCompress default web UI with Captain Compress mascot

Minimal UI (DISABLE_LOGO=true)

A clean, mascot-free interface great for professional or corporate environments:

bash
docker run -d --name imgcompress -p 3001:5000 -e DISABLE_LOGO=true karimz1/imgcompress:latest

ImgCompress minimal web UI without mascot, DISABLE_LOGO=true ImgCompress minimal web UI without mascot, DISABLE_LOGO=true

Open your browser at http://localhost:3001.

Update#

Keeping imgcompress up to date takes two commands.

bash
docker compose pull
docker compose up -d

bash
docker pull karimz1/imgcompress:latest
docker rm -f imgcompress
docker run -d --name imgcompress -p 3001:5000 karimz1/imgcompress:latest

Versions#

Most users should stick with latest.

Tag	Type	Who is it for?
`latest`	Stable release	Recommended for everyone.
`nightly`	Daily build	For testing new features before they ship.

⚠️Nightly builds

The nightly tag rebuilds every few days, for hot patches from the main branch. It may contain experimental features or bugs. Not recommended for production.

Platform Support#

imgcompress runs on any platform that supports Docker:

Platform	Status
Standard PCs & Macs	✅ Supported
Windows (Docker Desktop)	✅ Supported
Linux (any distro)	✅ Supported
Apple Silicon (M1/M2/M3/M4)	✅ Supported
Raspberry Pi 4+	✅ Supported

Web UI Guide