# home-operations/containers: opinionated rootless images for self-hosters

> The home-operations/containers repository builds Alpine and Ubuntu based application images that run rootless by default and expect you to pin by sha256 digest. It suits people who already run a container runtime and want fewer moving parts, not people looking for a one-click appliance.

**home-operations/containers** — Community project for building application containers

- Repository: https://github.com/home-operations/containers
- Website: https://github.com/orgs/home-operations/packages?repo_name=containers
- Stars: 434 · Forks: 50
- Language: Dockerfile
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/home-operations-containers

## What home-operations/containers is for

This is a collection of container images, not an application and not a runtime. The README opens by calling it "An opinionated collection of container images", and the opinions are spelled out in the mission statement: semantic versioning, rootless execution, multi-architecture builds, one process per container, logs to stdout, no s6-overlay, and a base of either Alpine or Ubuntu. The audience is the self-hoster or homelab operator who already runs Docker or Kubernetes and wants images that behave the same way across architectures without an init system layered on top. The repository is a build project, so what you consume is the published package, not a binary you compile. If you want a container for a specific app, the README points you at the GitHub Packages page for the repository rather than listing the catalogue inline. That is the first thing to internalise: the README describes policy, and the package registry describes inventory.

## Tag immutability and the sha256 digest requirement

The most consequential design decision is how tags work. The project does not publish immutable tags the way linuxserver.io or Bitnami are described as doing. Tags like ghcr.io/home-operations/home-assistant:rolling and ghcr.io/home-operations/home-assistant:2025.5.1 are both mutable in the project's own table, marked with a cross. Only the digest-qualified forms, ghcr.io/home-operations/home-assistant:rolling@sha256:8053... and ghcr.io/home-operations/home-assistant:2025.5.1@sha256:8053..., are marked immutable. So the tag tells you what the image is meant to be, and the digest tells you what it actually is. The README acknowledges this is "less visually appealing" and argues it ensures functionality and immutability. That is a real trade-off. You get reproducibility at the cost of a compose file that is unreadable at a glance, and you take on the job of updating digests yourself. The README names Renovate as the tool that can update containers based on digest or version changes, which is the intended workflow rather than manual editing.

## Rootless by default and the /config volume

The majority of containers run as a non-root user, 65534:65534, and the README states you can change user and group through your own configuration. That default matters for volume permissions: the Compose example sets user: 1000:1000 with the comment that the data volume permissions must match this user:group. Get that wrong and the container starts and then fails on writes, which is the most common first-run problem with this family of images. The same example sets read_only: true with a tmpfs mount at /tmp:rw, and notes that a read-only root may require mounting additional directories as tmpfs. The Kubernetes example mirrors this with allowPrivilegeEscalation: false, all capabilities dropped, and readOnlyRootFilesystem: true. Persistent configuration is hardcoded to /config inside the container, and the README says that in most cases the path cannot be changed. Plan your volume mounts around /config rather than expecting an environment variable to relocate it.

## Installing and running a first container

There is no installer. You pull an image from ghcr.io and run it with whatever runtime you already have. The README gives a Compose example for home-assistant that pins by digest, sets a non-root user, and makes the root filesystem read-only with a tmpfs at /tmp. The digest below is the one printed in the README, so treat it as an illustration and replace it with the digest of the tag you actually want.

```yaml
services:
  home-assistant:
    image: ghcr.io/home-operations/home-assistant:2025.5.1@sha256:516ae5c85089b3f2960cf2a21dc3c105356969499964fabf0b0358e5f3a7e0a2
    container_name: home-assistant
    user: 1000:1000 # The data volume permissions must match this user:group
    read_only: true # May require mounting in additional dirs as tmpfs
    tmpfs:
      - /tmp:rw
```

Before trusting the image, verify that GitHub CI built it. The README offers two routes. The first uses the gh CLI against the OCI reference.

```bash
gh attestation verify --repo home-operations/containers oci://ghcr.io/home-operations/${APP}:${TAG}
```

The second uses cosign and checks the attestation type against the workflow that produced it.

```bash
cosign verify-attestation --new-bundle-format --type slsaprovenance1 \
    --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
    --certificate-identity-regexp "^https://github.com/home-operations/containers/.github/workflows/app-builder.yaml@refs/heads/main" \
    ghcr.io/home-operations/${APP}:${TAG}
```

If an application only accepts configuration through command-line arguments, the README points at the Kubernetes documentation on defining commands and arguments, then shows the shape of the args list.

```yaml
args:
  - --port
  - "8080"
```

## Where this collection is the wrong choice

The README has an "Eschewed Features" section, and it is the clearest statement of the project's limits. There is no support for multiple channels of the same application. Prowlarr, Radarr, Lidarr and Sonarr publish only the develop branch, not the master or stable branch. qBittorrent is published only with LibTorrent 2.x, with a link to an issue for the reasoning. If your deployment policy requires stable-channel builds for those apps, this repository will not give them to you, and no amount of configuration changes that. The second limit is architectural: the project deliberately avoids s6-overlay, gosu and similar init mechanisms. Images that need a supervisor to bring up several daemons in one container are outside the model, because the model is one process per container. The third is lifecycle. Deprecation is announced with a release, and the README says deprecated containers remain in the registry for six months before removal. If you pin a digest and stop watching releases, you can sit on an image that is scheduled for removal without any pull failing until the day it does. Nothing in the README describes a rollback mechanism for a bad upstream release, so your rollback is your previous digest.

## How it compares to linuxserver.io and hotio.dev

The README credits hotio.dev and linuxserver.io as inspirations, and the contrast is explicit in the tag table. linuxserver.io and Bitnami are described as using immutable tags in the traditional sense, meaning the tag itself is the stable reference. Here the tag is a label and the digest is the reference. That changes your update tooling: with immutable tags you bump a version string, with this repository you bump a digest, and the README expects Renovate to do it. The second difference is the init layer. linuxserver.io images are widely used with s6-overlay style supervision, which this project rules out in favour of one process per container and stdout logging. The practical consequence is fewer background processes you did not ask for, and also no built-in place to hang a second daemon. A third difference is selection. linuxserver.io and Bitnami publish broad catalogues; this repository's contributing guide says to prefer official upstream images and to contribute here only when there is no official image, the official image lacks multi-architecture builds, it uses unconventional init, or it does not tag releases. That is a narrower remit by design.

## Maintenance, upgrades and the Apache-2.0 licence

The last push to the repository was on 2026-08-24, which is the same timestamp as release 2026.8.0. The two prior releases were 2026.7.1 on 2026-07-26 and 2026.7.0 on 2026-07-17, so the release cadence visible in the release history is roughly monthly. The repository is not archived. Upgrades are your responsibility: because tags are mutable, the upgrade path the README describes is digest pinning plus a tool like Renovate that watches for digest or version changes. That means your maintenance cost is mostly tooling and review, not patching the images yourself. The repository is Apache-2.0, and the LICENSE file sits at the top level. That covers the build recipes and any scripts in the repository. It does not automatically cover the applications packaged inside each image, which carry their own licences upstream; the README does not enumerate them, so check the licence of the specific application you deploy before you redistribute an image. None of this is legal advice, and if you are shipping images commercially you should read the upstream licence for each app rather than assuming the repository licence travels with it.

## Conclusion

Adopt it if you already run Docker Compose or Kubernetes, you want a single process per container, and you are willing to pin images by sha256 digest and let Renovate move them. Skip it if you need a stable versus develop channel for the same app (the README says Sonarr, Radarr, Lidarr and Prowlarr publish only develop, and qBittorrent only ships LibTorrent 2.x), or if you depend on s6-overlay style init scripts. Verify the signature of the exact tag you intend to run with gh attestation verify or cosign before you put it into production, and check the deprecation note in the release you are on, since deprecated images stay in the registry for six months before removal.

## FAQ

### How do I install a home-operations/containers image in Docker?

You do not install anything. You pull the image from ghcr.io and run it with Docker or Kubernetes, pinning the tag to a sha256 digest. The README's Compose example sets the user, mounts /config, and can enable a read-only root filesystem with a tmpfs at /tmp.

### Can I run home-operations/containers images on Proxmox?

The README only documents Docker Compose and Kubernetes deployment, so it does not describe a Proxmox path. If you run a container runtime inside a Proxmox VM or LXC, the image itself is unchanged, but the repository gives no Proxmox-specific instructions.

### What does "multi-architecture" mean for home-operations/containers?

The mission statement lists multi-architecture containers as one of the project's goals, and the contributing guide treats a lack of multi-architecture builds in an official upstream image as a reason to build one here. The README does not list which architectures are published per image.

### Why does home-operations/containers not publish a stable channel for Sonarr, Radarr, Lidarr and Prowlarr?

The README's Eschewed Features section states that these applications publish only the develop branch, not the master branch, and that the repository does not support multiple channels for the same application. It frames this as a consistency choice.

### Where does home-operations/containers store persistent configuration?

The README says the configuration volume is hardcoded to /config inside the container, and that in most cases the path cannot be changed. Mount your persistent data there and make sure the host permissions match the user you run as.

### How do I verify that a home-operations/containers image was built by GitHub CI?

The README gives two commands: gh attestation verify --repo home-operations/containers oci://ghcr.io/home-operations/${APP}:${TAG}, or cosign verify-attestation with --new-bundle-format and --type slsaprovenance1 against the app-builder workflow identity. Images are signed with the attest-build-provenance action.

## Sources

- [Official documentation](https://github.com/orgs/home-operations/packages?repo_name=containers)
- [Official README](https://github.com/home-operations/containers#readme)
- [Project repository](https://github.com/home-operations/containers)
- [Release notes](https://github.com/home-operations/containers/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/home-operations-containers