# Suwayomi-Server-docker is a container image that runs the reader server as a non-root user

> This repository packages Suwayomi-Server for Docker and Podman: a multi-arch Ubuntu based image, a compose template, a Quadlet unit for rootless Podman, and an environment variable table for overriding server settings at startup. The image is built from a Temurin JDK base and the settings can also be changed at runtime through the web interface, which is where the design gets its one wrinkle.

**Suwayomi/Suwayomi-Server-docker** — Run Suwayomi-Server in a docker container

- Repository: https://github.com/Suwayomi/Suwayomi-Server-docker
- Stars: 572 · Forks: 89
- Language: Shell
- License: MPL-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/suwayomi-suwayomi-server-docker

## One image, five architectures, and the port you already expect

The repository is the container packaging for Suwayomi-Server, and the readme states the arrangement plainly: run Suwayomi-Server inside a docker container as a non-root user. The server then listens on http://localhost:4567.

The image itself is published on the GitHub container registry, and the readme links both the container releases and the Dockerfile. It is multi-arch, covering linux/amd64, linux/arm64/v8, linux/ppc64le, linux/s390x and linux/riscv64, and it is small because it is based on Ubuntu Linux.

The data location is fixed and it matters for any deployment: the Suwayomi data lives in /home/suwayomi/.local/share/Tachidesk. That path appears in the compose file as a bind mount, which is the difference between a container that keeps your library across an image upgrade and one that does not.

The status table at the top of the readme distinguishes a stable channel from a preview channel, and each channel has its own badge and its own package page. The stable version badge reads its value out of a version file in the repository, scripts/tachidesk_version.json, querying the stable key, which means the badge reflects the same file the build uses rather than a hand maintained number.

The primary language of the repository is Shell, and the top level entries are exactly what you would expect for a packaging repository: a Dockerfile, a docker-compose.yml, a docker-compose-postgresql.yml, a suwayomi-server.container for Podman, a data/ directory, a scripts/ directory, and a renovate.json for dependency updates.

## The compose file is small, and the commented part is the real documentation

The compose template that ships in the repository defines two services, the server itself and an optional helper for sites that block automated access. The server service looks like this:

```yaml
services:
  suwayomi:
    image: ghcr.io/suwayomi/suwayomi-server:preview
    # user: 1000:1000
    environment:
      - TZ=Etc/UTC # Use TZ database name from https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      # Comment these out if you do not use the flaresolverr container at the bottom of this file
      - FLARESOLVERR_ENABLED=true
      - FLARESOLVERR_URL=http://flaresolverr:8191
```

The volume and port mapping are the two lines that decide whether your setup works:

```yaml
    volumes:
      - ./data:/home/suwayomi/.local/share/Tachidesk
    ports:
      - "4567:4567"
    restart: on-failure:3
```

The bind mount keeps the library on the host, and the restart policy gives the container three attempts before Docker gives up.

The second service is the flaresolverr container, pulled from a separate image, with the same timezone setting and a restart policy of unless-stopped. It is not required, and the compose file says so in a comment on the environment line above it.

The long commented block at the top of the service is the most useful part of the file for a new user. It warns that server settings can be changed during runtime in the WebUI, and that providing an environment variable will OVERWRITE the current setting value when starting the container. Then it lists the shape of the settings you can set, with BIND_IP, BIND_PORT, SOCKS_PROXY_ENABLED, DOWNLOAD_AS_CBZ, AUTH_MODE, AUTH_USERNAME, AUTH_PASSWORD and EXTENSION_STORES as the examples.

## Environment variables win over the web interface, and the readme says so twice

This is the one design decision that trips people up, and the readme handles it with two separate callouts.

The first is a caution that providing an environment variable will overwrite the current setting value when starting the container. The second is a tip that most of the time you do not need to use environment variables, instead settings can be changed during runtime via the webUI, which will be rendered useless when providing an environment variable.

So there are two configuration paths and they conflict. The web interface is convenient and persistent for that container's lifetime, and the environment is authoritative at start. If you set a variable, the web interface stops being the source of truth for that setting, and the next restart resets whatever you changed in the browser back to the value you baked into the environment.

The advice that follows from this is to decide which one owns each setting before you start, rather than discovering the conflict after you have changed something in the browser and wondered why it reverted.

There is one more convenience worth knowing, and it is a good one. Passwords can be provided as files by appending _FILE to the variable name, so you can set SOCKS_PROXY_PASSWORD_FILE=/path/to/myfile and Suwayomi uses the content of that file as the socks proxy password. For a container that handles credentials, keeping them in a file rather than in the environment or in a compose file is a reasonable habit.

For defaults, the readme points at server-reference.conf in the Suwayomi-Server repository, which holds the default values for every variable. The environment variable table in the readme begins with TZ defaulting to Etc/UTC, BIND_IP defaulting to 0.0.0.0 with the note that you almost never want to change it, and BIND_PORT defaulting to 4567.

## Logs go to stdout, which is the point of running it this way

The readme is brief about logging, and the behaviour it describes is the main operational advantage of the container over a manual install.

Logs are sent to stdout. That allows Docker to manage the logs, and you view them using docker logs --tail=1000 with the container name, or if you are using the compose file, docker compose logs --tail=1000 suwayomi.

By default, Docker stores logs indefinitely, and the readme links two ways to change that: setting up logging globally through the Docker engine documentation, or editing the compose file with a logging driver.

That default is worth thinking about. Indefinite log retention on a container that scrapes web pages and tracks download progress is a slow disk fill on a small VPS, and the fix is a two line change in the compose file, but only if you know it is there.

The Podman path is a first class option rather than an afterthought. The readme points at a suwayomi-server.container template in the repository for creating and starting Suwayomi as a rootless Podman container. Rootless is the interesting part: a rootless container cannot simply write to system paths, which is consistent with the server itself running as a non-root user inside the image.

The second compose file in the repository, docker-compose-postgresql.yml, suggests the intended alternative for anyone who wants the server on PostgreSQL rather than the built-in database, and it is worth knowing it exists before you have already populated a library into the default store.

## The Dockerfile is a Java build with a CEF download step

The Dockerfile explains where the complexity lives, and it is not in the packaging of a single jar.

The build stage uses a Temurin JDK image, eclipse-temurin:25.0.4_7-jdk-noble, and the runtime stage uses the matching JRE, eclipse-temurin:25.0.4_7-jre-noble. The server itself is a JVM application, and the image is assembled around that runtime.

The build stage has one optional piece of work. It takes a TACHIDESK_ABORT_HANDLER_DOWNLOAD_URL argument, and if that argument is non-empty it installs curl and gcc, downloads a C source file, compiles it with gcc -fPIC against the JDK headers into a shared object called catch_abort.so, and then purges gcc again. That is a native abort handler compiled against the JVM, and it is opt-in through a build argument, so the default build does not do it.

The runtime stage installs more than you would expect for a headless server: envsubst from the gettext project, unzip for reading the server-reference.conf out of the jar, tini as a tiny init system to handle orphan processes for graceful restart, and ca-certificates. It then extracts the Java CA certificate store with p11-kit so that TLS trust works in the image.

There is a second conditional in the runtime stage. The TACHIDESK_KCEF argument controls whether Chromium Embedded Framework is installed, and it defaults to auto-detection: the condition installs the CEF libraries when the argument is y, or when it is empty and the target platform is linux/amd64 or linux/arm64. Those libraries are the usual set for a headless browser, and the comment above them notes the fonts are there for Asian characters. The Dockerfile also copies a script, scripts/kcef_download.sh, into the image for that step.

## Where a packaged server image is the wrong shape for you

The first limitation is that the configuration model is not neutral, and the readme is upfront about it. If you want to change a setting from the web interface and have it stick across restarts, this image is the wrong place, because the environment overwrites the stored value at start. That pushes you toward either the environment for everything, which means a container edit on every change, or the web interface for everything, which means the variables you set at start stop being the source of truth for that setting.

The second limitation is the browser dependency, and it is not small. The image can pull in Chromium Embedded Framework and a stack of shared libraries, which is a large amount of container for a server whose main job is to talk to source sites and hand you files. On a small machine, or on a platform where linux/s390x or linux/riscv64 has no Chromium build, that path is a problem. The Dockerfile auto-detects the platform for the CEF decision, which means the behaviour differs by architecture, and that is the kind of difference that is easy to miss.

The third is that this is a packaging repository, not the server. The server itself lives in the Suwayomi-Server repository, and this one tracks it, with a stable and a preview channel, a renovate configuration for dependency updates, and a version file that feeds the badge. The upgrade path is therefore a pull of a new tag, and the compatibility question, which server build works with which image, is answered by the channel you pick rather than by anything in this repository.

The alternative to weigh is running the server directly, which the server repository supports on its own, or using a different packaging for the same server. The difference is that this repository gives you the non-root user, the multi-arch builds, the rootless Podman unit, the compose template with the data mount in the right place, and stdout logging, all of which you would otherwise assemble yourself.

## Conclusion

Adopt this repository if you want to run Suwayomi-Server in a container rather than on the host, since the image is multi-arch, runs as a non-root user, ships a compose file and a rootless Podman unit, and sends logs to stdout so Docker manages them. Do not adopt it if you want to change server settings from the web interface, because the readme states that supplying an environment variable overwrites the current setting at container start and renders the runtime change useless. Verify first that the stable or preview image tag you pull matches the server build you want, that your data directory mount points at the path the image expects, and which settings you intend to lock down through the environment rather than through the UI.

## FAQ

### How do I run Suwayomi-Server in Docker?

Use the docker-compose.yml template in the repository, which defines the suwayomi service pulling the ghcr.io/suwayomi/suwayomi-server image, mounting ./data at /home/suwayomi/.local/share/Tachidesk and publishing 4567:4567, so the server is then reachable at http://localhost:4567.

### Can I run Suwayomi as a rootless Podman container?

Yes. The repository ships a suwayomi-server.container template that is described as being for creating and starting Suwayomi as a rootless Podman container, alongside the compose file for Docker users.

### Do environment variables override settings I change in the web interface?

Yes. The readme states that providing an environment variable will overwrite the current setting value when starting the container, and that most of the time you do not need environment variables since settings can be changed during runtime via the webUI, which is rendered useless when providing an environment variable.

### Which container architectures are supported?

The images are multi-arch, covering linux/amd64, linux/arm64/v8, linux/ppc64le, linux/s390x and linux/riscv64, and the size is small because the base is Ubuntu Linux. The server runs as a non-root user inside the container.

### How do I pass a password to the Suwayomi container without putting it in the environment?

Append _FILE to the variable name and point it at a file, for example setting SOCKS_PROXY_PASSWORD_FILE=/path/to/myfile so that Suwayomi uses the content of that file as the socks proxy password. Default values for every variable are in the server-reference.conf file in the Suwayomi-Server repository.

## Sources

- [Issues](https://github.com/Suwayomi/Suwayomi-Server-docker/issues)
- [License: MPL-2.0](https://github.com/Suwayomi/Suwayomi-Server-docker/blob/main/LICENSE)
- [README](https://github.com/Suwayomi/Suwayomi-Server-docker/blob/main/README.md)
- [Suwayomi/Suwayomi-Server-docker on GitHub](https://github.com/Suwayomi/Suwayomi-Server-docker)

---

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