MAZANOKE: a self-hosted image optimizer that never uploads your files

The problem MAZANOKE solves, and who it is actually for

Most free online image compressors ask you to upload a file to a server you do not control. The README frames MAZANOKE as "an alternative to questionable 'free' online tools", and the target audience is explicit: "everyday people", designed to be shared with family and friends. That is a narrower claim than it sounds. This is not aimed at a build pipeline that needs to crunch ten thousand product photos, and it is not aimed at a designer who wants a Photoshop replacement. It is aimed at the person who has a phone screenshot that is 4 MB, wants it under a chat app's limit, and does not want that screenshot sitting on someone else's disk. The privacy story is structural rather than policy-based: the README states the app works offline and processes images on-device, so there is no upload step to trust in the first place. The homepage is mazanoke.com, but the README treats self-hosting as the stronger option, which tells you where the project's priorities sit.

How the optimization actually happens: browser-side compression, not a server job

The architecture follows from the constraint. MAZANOKE ships as static files: index.html, an assets directory, a manifest.json, a favicon and a service-worker.js. The Dockerfile's first stage is a Node image that copies exactly those files into an nginx html directory and runs scripts/environment.common.js against them; the second stage is nginx:alpine serving the result on port 80. There is no application server, no database and no upload endpoint in the compose file. The work is done by the browser, and the README credits the libraries doing it: Browser Image Compression, heic-to with libheif and libde265 for HEIC input, and JSZip, which is what lets the app hand back a zip when you process several images at once. The service worker is what makes the offline claim real: once the app is cached, the page can load without a network connection, and the image never has to leave the tab. This is also why the project's primary language is listed as CSS. The interesting part of the repository is the interface and the build plumbing, not a compression engine the maintainers wrote themselves.

Installing MAZANOKE with Docker and optimizing your first image

The README's Docker path uses Docker Compose, and the repository ships a compose.yaml that matches it. The service maps host port 3474 to container port 80 and sets a restart policy of unless-stopped, so the container comes back after a reboot.

services:
  mazanoke:
    container_name: mazanoke
    image: ghcr.io/civilblur/mazanoke:latest
    ports:
      - "3474:80"
    restart: unless-stopped

Start it with the usual compose command from the directory holding that file. The README says to access the app at http://localhost:3474, so a browser request to that address should return the MAZANOKE interface rather than an nginx welcome page.

docker compose up -d

The README points at docs/configuration.md for available environment variables, and the Dockerfile shows one of them by name: METATAGS, which is described there as toggling optional SEO metatags at runtime. The container's entrypoint runs metatags.sh and basicauth.sh before starting nginx, and the image installs apache2-utils to support the basic authentication script. If you deploy this on a network where you do not want anonymous access, that script is the mechanism to look at, and the README itself does not document it.

If you would rather not run a container at all, the README's local path is to download the latest source code release and open index.html in a browser. That is the whole install. The third path is the installable web app: visit mazanoke.com or your own instance, click the Install button in the top right, and a shortcut is added to the device that can be used offline. Once the app is open, the workflow the README describes is: add images, adjust quality, set a target file size, set max width and height, and convert between JPG, PNG, WebP and ICO. HEIC, AVIF, TIFF, GIF and SVG are listed as input formats only, so treat those as sources rather than destinations. Images can also be pasted from the clipboard, which is faster than dragging files for screenshots.

What MAZANOKE does not do

The honest limitation is the one the design creates: everything runs in a browser tab, so the ceiling on batch size is the memory and CPU of the machine holding the browser, not the machine running the container. A server with 32 GB of RAM does nothing for you here. If you need to process a directory of images from a shell, MAZANOKE has no CLI, and the README documents no HTTP API you could call from a script. The Docker image is a static file server plus a couple of shell scripts, not a service with endpoints. There is also no documented rollback or versioning story: the compose file pins the image tag to latest, and the README does not tell you how to move to a specific release tag or what changes between them. The release history shows v1.1.7 on 2026-09-20, v1.1.6 on 2026-05-09 and v1.1.5 on 2025-06-09, so releases are not frequent, and pulling latest means you get whatever the most recent tag contains. Finally, EXIF removal is listed as a feature, which is good for privacy and bad if you actually needed the capture date or camera metadata to survive. There is no documented way to keep it.

MAZANOKE against Squoosh and desktop compressors

The closest reference point in the search data is Squoosh, Google's browser-based image compressor. The two share the core idea: the image is decoded, re-encoded and compared in the browser, and nothing is uploaded. The difference is in what surrounds that idea. Squoosh was built as a demonstration of codec quality, with side-by-side visual comparison and fine-grained per-codec controls, and it is a hosted page you visit. MAZANOKE is built to be installed: it ships a manifest.json, a service worker and a Dockerfile, so you can run it on your own hardware and hand the URL to people who do not care which encoder is used. It also has a target file size control, which is the setting a non-technical user actually wants, rather than a quality slider they have to interpret. Desktop tools such as Caesium take the opposite approach: they run natively on your machine and can walk a folder of files, which is the batch case MAZANOKE does not cover. The split is simple. If your input is a folder and your output is a folder, a desktop compressor fits better. If your input is a handful of images and your requirement is that they stay on the device, MAZANOKE's installable web app is the more practical shape.

Licence and the cost of keeping an instance running

MAZANOKE is licensed under GPL-3.0, and the Dockerfile's image labels record the licence as GPL-3.0-only. The practical consequence for most readers is that running the published image or self-hosting the app for your family or team does not oblige you to publish anything. If you modify the source and distribute the result, the GPL's source-availability terms come into play. That is a description of the licence text, not legal advice, and if you plan to ship a modified version inside a product, read the licence or ask someone qualified. On maintenance cost, the last push to the repository was on 2026-09-20, which is recent, and the most recent release is v1.1.7 from the same day. The gap between v1.1.5 and v1.1.6 was about eleven months, so do not expect a steady stream of changes. The upgrade procedure is not documented in the README: with the compose file pinned to latest, updating means pulling the image again and recreating the container, and the README does not describe what to check afterwards. Because the app is static files with no database, there is no migration step and nothing to back up beyond your own configuration, but that is an inference from the repository layout rather than a documented guarantee.

Editorial conclusion

Adopt MAZANOKE if you want an image optimizer your family or colleagues can open in a browser without sending files to a third party, and you are comfortable running a container behind nginx. Do not adopt it if you need server-side batch processing, a CLI, or an API to call from a build pipeline: the README documents none of those. Before deploying, verify two things in the repository: the environment variables listed in docs/configuration.md, and whether the basic authentication script is enabled in your image, since the Dockerfile installs apache2-utils and copies basicauth.sh into the entrypoint.

Frequently asked questions

Official sources

1. civilblur/mazanoke on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases