Shimmie2: a self-hosted image gallery you can install on a disk or in a container

A small PHP image gallery, and what kind of image gallery it is

Shimmie describes itself as an easy to install community image gallery, and the parenthetical in the repository description is the more precise term, since the project is a booru. A booru is defined by its data model rather than by its interface: images are uploaded into albums or posts, tagged by anyone who can see the tag, and browsing happens through tag search rather than through folders and albums.

That data model determines who likes it and who does not. If you want a shared gallery where members upload pictures and the interesting navigation is a tag cloud and a search box, Shimmie fits. If you want a media library for a household with albums, an event gallery with ordering, or a photo workflow that treats originals as files on a disk with the web application as a viewer, then a booru's tag-centric model works against you.

The project is PHP, licensed under the GNU GPL Version 2 unless a file says otherwise, and hosted at code.shishnet.org with the GitHub repository as the primary source. The README points at a Matrix room for chat, and there is a Codespaces badge for a hosted development environment.

The release line is active. Version 2.12.5 was tagged on 2026-10-15, with 2.12.4 on 2026-10-05 and 2.12.3 on 2026-10-03, and the last push to the repository was on 2026-10-15. Three point releases in the same month is the clearest signal in the whole README about how the project is being worked on.

The core, ext and themes layout tells you how to extend it

The repository layout is a good map of the architecture, and there are three directories that matter to anyone who wants to change behaviour.

The `core/` directory holds the application itself, and it is where the configuration lives, specifically in `core/Config/SysConfig.php`, which the README links as the advanced configuration reference. Reading a single PHP file to understand the tunable settings of the whole application is a considerably better experience than hunting through a settings screen in the browser.

The `ext/` directory holds the extensions, and this is the extension point that most users of the project will care about. Features in a booru tend to be additive, upload handling, transcoding, comment systems, rating, extra search syntax, so a directory of separately loadable extensions is a sensible design for that kind of product. It also means that adding a feature does not require touching the core.

The `themes/` directory holds the presentation layer, and separating themes from extensions is a deliberate choice: the same site can be reskinned without any of the functional extensions changing.

Around those three sit the parts of a normal PHP project. There is an `index.php` entry point, a `.htaccess` file, a `composer.json` and `composer.lock` for dependencies, a `phpunit.dist.xml` for tests, a `phpstan.dist.neon` for static analysis, a `.php-cs-fixer.dist.php` for code style, and a `tests/` directory. There is also a `SECURITY.md` and a `Dockerfile` at the top level, plus `.docker/` and `.devcontainer/` directories for the container and development environment setups.

The combination of PHPUnit, PHPStan and php-cs-fixer configured in the repository is a signal about how the code is maintained, and it is a stronger signal than the feature list.

The Dockerfile: PHP 8.4, nginx, ffmpeg and three database drivers

The container image is the most concrete piece of documentation in the repository, and the Dockerfile explains the deployment shape better than any prose would.

The build starts from a Debian trixie base and pulls in a static ffmpeg and ffprobe build, which tells you that media handling is part of the product rather than an add-on.

FROM debian:trixie AS base
COPY --from=docker.io/mwader/static-ffmpeg:9.0 /ffmpeg /ffprobe /usr/local/bin/
RUN apt update && \
    apt upgrade -y && \
    apt install -y --no-install-recommends \
    supervisor \
    nginx \
    php${PHP_VERSION}-cli php${PHP_VERSION}-fpm \

The PHP version is a build argument defaulting to 8.4, and the same variable names every extension, which is the clearest sign that the image is meant to be rebuilt on a newer PHP by changing one value. The package list continues with the GD, zip, XML, mbstring and curl extensions for image handling and parsing, and then three separate database drivers.

    php${PHP_VERSION}-pgsql php${PHP_VERSION}-mysql php${PHP_VERSION}-sqlite3 \
    php${PHP_VERSION}-memcached \
    curl imagemagick zip unzip librsvg2-bin git ca-certificates && \

Three drivers, PostgreSQL, MySQL and SQLite, mean the gallery can run on whatever database you already run. ImageMagick and librsvg2-bin are the image and vector rendering tools, which is how thumbnails and SVG previews are produced.

The build is staged rather than monolithic, and the comments in the file explain why.

FROM dev-tools AS build
COPY composer.json composer.lock /app/
WORKDIR /app
RUN composer install --no-dev --no-progress --optimize-autoloader
COPY . /app/

The comment above it says the build is done in its own stage so the composer tooling does not end up in the final image, and the dev-tools stage notes that Composer has 100MB of dependencies, which is a fair reason to keep them out. There is a separate devcontainer stage that exposes port 8000 and runs the app through a script, and the final run stage is built from the lean base image.

The README also links a Codespaces badge, so a developer can get a running environment without assembling the container themselves.

Installing on a disk, in Docker, and the upgrade path between them

The documentation section is short and points at a wiki, with four links that map onto the decisions an installer has to make.

The first is a page for installing straight on disk, the second for installing in a Docker container, and the third is the upgrade process. The fourth is the advanced configuration file in the repository itself, `core/Config/SysConfig.php`, and the remaining links are the developer notes and a page of high performance notes.

That list tells you the project expects two deployment styles and treats them as first class, which is unusual for a small gallery application and useful if you have to move between them.

The upgrade page being a documented, separate artefact is the part worth noting. An application that stores uploaded images, tags, comments and user accounts in a database has real upgrade risk, and the fact that there is a named upgrade process in the wiki, rather than a note in the README, suggests the maintainer takes it seriously. What the README does not do is tell you the upgrade policy itself, whether versions can be skipped, or what a rollback looks like, and the version numbering suggests a fairly active release cadence, with three point releases inside a month, so an operator who defers upgrades for long will be doing a bigger jump later.

The high performance notes page is another signal of where the project is aimed. A booru with a large tag space and a lot of images is a database and thumbnail problem before it is a scripting problem, and having a page on performance implies the project has users in that situation. The README does not summarise what those notes contain.

One practical detail comes from the container side rather than the wiki. The Dockerfile installs `supervisor` alongside nginx, which means the image runs a process supervisor for the PHP workers, and the devcontainer stage exposes port 8000, so the development environment serves the application on that port rather than through nginx.

GPL-2.0 and what the licence means for a customised gallery

The licence section of the README is unusually explicit about the part that trips people up, which is what happens to your own modifications.

The stated position is that all code is released under the GNU GPL Version 2 unless mentioned otherwise, that if you give Shimmie to someone else you have to give them the source, and that the README adds the reason this is easy, since PHP is an interpreted language and the source is what runs. Then the part that matters for site operators: if you want to add customisations to your own site, those customisations belong to you, and you can do what you want with them.

This is a real and unusual property for a web application, and it is worth being precise about what it does and does not mean. The themes and extensions you write for your own instance are yours, and you are not obliged to publish them to the users of your gallery or to anyone else. The obligation attaches to the licensed code itself, so if you distribute the application, modified or unmodified, you have to pass on the corresponding source.

The README does not give legal advice and neither does this article, so a site that plans to modify Shimmie and keep the modifications private, or to run a customised instance for clients, should read the GPL-2.0 text and, if the answer matters to them, ask someone qualified. What the README does establish clearly is the intent, which is that customisation is expected and the customiser keeps ownership of their own work.

The `SECURITY.md` file at the top of the repository is worth reading in the same frame, since a gallery that accepts uploads from the internet has a public attack surface and the project has a place for reporting problems in it.

Where a booru is the wrong tool

There are clear cases where this application is the wrong choice, and the strongest one is scale of the wrong kind.

A booru's model is built for many small images with rich metadata. If your requirement is a handful of large photographs, the tag taxonomy is overhead you will not use, the thumbnail pipeline will make copies you did not ask for, and the search interface will be less convenient than a folder. The same applies to any archive where the primary structure is chronological, per event, or per person rather than per tag.

The second wrong case is a public upload surface with a hostile audience. The application is a PHP web application that accepts files from the internet and renders them. The repository shows a serious engineering setup with static analysis, tests, a security policy and a Codespaces environment, and there is a high performance notes page, but none of that is a substitute for a stated security posture in the README, and the README says nothing about rate limiting, moderation workflow or what happens to an upload that is not an image.

The third wrong case is a team that wants a supported product. This is a community project with a single primary maintainer, released under the GPL, with the documentation living on a personal wiki rather than in a versioned documentation set. That is not a criticism, it is simply what the project is, and it means the cost of running it includes reading the source when the documentation runs out.

A reasonable middle path exists, and it is how the project itself is set up. Run the gallery for what it is, a tag driven community image board, with the extension system as the place to add the one thing your community actually needs, and use the database drivers and the container image to keep the operational side conventional. The alternative to that is to pick a media server with a different data model, and the time to make that decision is now, before the first upload.

Editorial conclusion

Shimmie is a reasonable choice for a small gallery, a hobbyist booru or a community archive where the whole site is a PHP application you can read, with the extension directory giving a clear place to add features without touching the core. It is a poor fit for a large media library that needs transcoding pipelines, tiered storage, CDN delivery or a hardened public upload surface, since none of that is what the project is built for. Verify first which database you will use, because the container image ships drivers for PostgreSQL, MySQL and SQLite and the choice affects your upgrade path, then read the upgrade notes in the project wiki before you run the first update on a live site.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. Project website
3. README
4. Releases
5. shish/shimmie2 on GitHub