Stashix

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Stashix is configured with environment variables. With Docker Compose they live in the .env file next to docker-compose.yml. See Installation for a first setup.

Required

Variable	Default	What it does
`SECRET_KEY_BASE`	none	Encrypts and signs sessions and cookies. Generate with `openssl rand -base64 48`.
`JWT_SECRET`	none	Signs login tokens. Use a different value from `SECRET_KEY_BASE`.
`STASHIX_ENCRYPTION_KEY`	none	Base64 32-byte key that encrypts stored metadata source credentials. Generate with `openssl rand -base64 32`.
`DATABASE_URL`	`postgresql://stashix:stashix@db/stashix`	PostgreSQL connection, as `ecto://user:password@host/database`.
`LIBRARIES_PATH`	`./libraries`	Your media folder on the host, not a path inside the container. Compose mounts it read-write at `/libraries`, and each library in Stashix points at a folder under that, such as `/libraries/comics`. Read-write so metadata can be saved to your files; see Metadata in your files.

LIBRARIES_PATH is used only by Docker Compose to mount the folder; Stashix itself never reads it. It used to be called LIBRARY_PATH, and .env files with the old name keep working.

How the Scanner Works

Mon, 01 Jan 0001 00:00:00 +0000

Supported formats

Stashix reads the following file types:

Format	Extension	Notes
Comic Book ZIP	`.cbz`	Most common; ZIP archive of images
Comic Book RAR	`.cbr`	RAR archive of images
Comic Book 7-Zip	`.cb7`	7-Zip archive of images
EPUB	`.epub`	Image-based EPUBs, such as manga (see below)
PDF	`.pdf`	Comics and books as PDF

All other extensions are silently ignored. Files are matched case-insensitively (.CBZ and .cbz are equivalent).

Installation

Mon, 01 Jan 0001 00:00:00 +0000

This guide runs Stashix and its PostgreSQL database with Docker Compose. Check what you need before installing first.

Install

Download the Compose files

Make a folder for Stashix and fetch the Compose file and the example settings into it:

mkdir stashix && cd stashix
curl -fsSLO https://raw.githubusercontent.com/aroy-art/stashix/main/docker-compose.yml
curl -fsSL -o .env https://raw.githubusercontent.com/aroy-art/stashix/main/.env.example

Fill in the secrets

Stashix needs three random secrets and a database password. Paste these lines into your terminal, in the stashix folder, to generate them and write them into .env:

set_env() { sed -i "s|^$1=.*|$1=$2|" .env; }
DB_PASSWORD=$(openssl rand -hex 24)
set_env SECRET_KEY_BASE "$(openssl rand -base64 48)"
set_env JWT_SECRET "$(openssl rand -base64 48)"
set_env STASHIX_ENCRYPTION_KEY "$(openssl rand -base64 32)"
set_env POSTGRES_PASSWORD "$DB_PASSWORD"
set_env DATABASE_URL "ecto://stashix:$DB_PASSWORD@db/stashix"

Run them once, before the first start. On macOS, change sed -i to sed -i '' in the first line.

Warning

Back up .env. If STASHIX_ENCRYPTION_KEY is lost or changed, the metadata source credentials Stashix has stored can’t be read anymore. Upgrading an install that ran without this key? See Adding the key to an older install.

Prefer to fill them in by hand?

Open .env and set each value to the output of its command:

Setting	Command
`SECRET_KEY_BASE`	`openssl rand -base64 48`
`JWT_SECRET`	`openssl rand -base64 48` (run it again for a different value)
`STASHIX_ENCRYPTION_KEY`	`openssl rand -base64 32`
`POSTGRES_PASSWORD`	Any password made of letters and numbers
`DATABASE_URL`	`ecto://stashix:<password>@db/stashix`, with the same password

Point Stashix at your library

Open .env and set the values only you know:

Setting	Set it to
`LIBRARIES_PATH`	Your media folder on this machine (the host), such as `/srv/media`. Not a path inside the container or in Stashix.
`PHX_HOST`	The hostname you’ll use to reach Stashix, such as `stashix.home.lan`.
`PUID` / `PGID`	A user and group that can read and write `LIBRARIES_PATH`. `id -u` and `id -g` print yours.

Compose makes LIBRARIES_PATH appear inside the container as /libraries. Stashix only sees that side, so the folders you add as libraries later start with /libraries:

On this machine Inside Stashix
/srv/media -> /libraries
/srv/media/comics -> /libraries/comics <- add as a library
/srv/media/manga -> /libraries/manga <- add as a library

Start Stashix
```
docker compose up -d
```
The first start pulls the images and creates the database, which can take a minute. The Stashix image comes from the GitHub Container Registry as ghcr.io/aroy-art/stashix.
Finish setup in the browser

Open http://<your-server>:4000. A setup wizard asks you to create the admin account. Then add a library. Enter its folder as Stashix sees it, under /libraries (for example /libraries/comics), not the path on your machine.

Stashix scans it straight away. Watch the progress under Admin → Libraries.

File Structure

Mon, 01 Jan 0001 00:00:00 +0000

The scanner uses folder structure as its primary grouping signal — a subfolder becomes a series, the files inside become its issues. Metadata embedded in the files or their names enriches that grouping but does not override it.

The two patterns

Series in a subfolder (recommended)

Place all issues of a series in one folder named after the series. The folder name becomes the series name.

Introducing Stashix

Wed, 04 Nov 2026 00:00:00 +0000

Stashix is a self-hosted library for comics and ebooks. You point it at the folders where your files already live, and it turns them into a shelf you can browse, search and read from any browser on your network.

This site is its new home: documentation, guides and release notes in one place.

Why Stashix

Most collections start as a folder of .cbz files and grow into something nobody can find their way around. Stashix keeps your files where they are and builds a library on top of them:

Stashix 0.0.1

Mon, 01 Jan 0001 00:00:00 +0000

First public release.

Stashix

Configuration

Required

How the Scanner Works

Supported formats

Installation

Install

Download the Compose files

Fill in the secrets

Point Stashix at your library

Start Stashix

Finish setup in the browser

File Structure

The two patterns

Series in a subfolder (recommended)

Introducing Stashix

Why Stashix

Stashix 0.0.1