Staaash

Important

Staaash is in beta. Expect some bugs and breaking changes between pre-releases. Do not use it as your only copy of important files — set up a 3-2-1 backup strategy before you start.

---

Staaash is a self-hosted file drive for people who want their files on their own server.

Why Use It

• Your files stay on storage you control.
• Sharing is built in, with public links for files and folders.
• Invite friends or family and give them their own space.
• Built for real home use: uploads, folders, sharing, backups, and restore checks.

Upload files, organize folders, invite trusted users, and share links without handing the whole thing to someone else's cloud. It is built for self-hosters who want something small enough to understand and useful enough to run at home.

If Immich is your self-hosted photo library, Staaash aims to be your self-hosted file drive.

Installation

Requirements: Docker with the Compose plugin.

Windows and Linux

1. Go to the releases page and download docker-compose.yml and example.env from the release you want into the same folder. Release files select that exact version tag; files on main may include unreleased changes.

2. Rename example.env to .env.

3. Open .env, set DB_PASSWORD to a secure value (you can use something like pwgen), and change any other settings you want.

4. Run:

   docker compose up -d

Staaash is now running at http://localhost:2113.

The first account you register becomes the owner. Subsequent accounts require an invite from the owner.

Optional release verification

Advanced users can also download release-manifest.json and SHA256SUMS from the same release to verify the files. The manifest records the workflow-verified immutable image reference. To pin that digest, set STAAASH_VERSION to its v1.2.3@sha256:... value instead of the normal v1.2.3 tag.

If you use CasaOS or another container UI, select the same readable release normally, for example ghcr.io/itsmeares/staaash:v1.2.3.

Reverse proxies

For a working Caddy example, see docs/operations/reverse-proxy.md.

If you put Staaash behind Caddy, Nginx, Traefik, or another reverse proxy, preserve the original Host header. Staaash rejects cross-origin mutating requests by comparing the browser Origin host to the request Host.

Use one public address consistently. Loading the app from https://staaash.example.com and posting to a direct server IP, LAN IP, or different port can fail by design.

SECURE_COOKIES is optional. By default, Staaash uses secure cookies on HTTPS and non-secure cookies on plain HTTP. Only set SECURE_COOKIES if you need to force cookie behavior. If your HTTPS proxy forwards traffic to Staaash over HTTP, make sure it sends x-forwarded-proto: https.

Upgrading

Change the exact release tag in your existing .env:

- STAAASH_VERSION=v1.2.3
+ STAAASH_VERSION=v1.2.4

Then run:

docker compose pull
docker compose up -d

Replace or update docker-compose.yml only when the target release notes say its Compose definition changed. Migrations run automatically on startup. These commands support upgrades between compatible releases in the Postgres 18 RC/current release line.

Warning

Alpha and beta releases cannot be upgraded to the RC or v1 release line. Use a fresh installation of the current release. Do not reuse an alpha/beta deployment's internal database or storage directories as the data directories for the current installation.

Data locations

What	Default path
Uploaded files	./library
Database	./postgres

Both paths are relative to where docker-compose.yml lives. Change them in .env before first run.

With the default Postgres 18 container, ./postgres is still the folder you back up. Inside the container, Postgres stores the actual cluster under its versioned data directory.

Backup And Restore

Back up both the database and uploaded files. In the default Docker setup, that means backing up ./postgres and ./library together.

See docs/operations/backup-restore.md for the restore checklist.

Documentation

• docs/architecture.md - system shape, storage model, and design boundaries
• docs/operations/backup-restore.md - simple backup and restore checklist

Local Development

Staaash is a PNPM workspace monorepo.

Next.js · TypeScript · Prisma · PostgreSQL

Repository Layout

• apps/web - web app and server routes
• apps/worker - background worker runtime
• packages/config - shared TypeScript config
• packages/db - Prisma schema and DB helpers
• docs - architecture reference

Development Setup

1. Copy dev.example.env to .env.local at the repo root.

2. Start PostgreSQL. The default .env.local expects postgresql://staaash:staaash@localhost:5432/staaash. If you want a local Docker container that matches those values, run:

   docker run --name staaash-postgres -e POSTGRES_USER=staaash -e POSTGRES_PASSWORD=staaash -e POSTGRES_DB=staaash -p 5432:5432 -v staaash-postgres-data:/var/lib/postgresql -d postgres:18-alpine

   After that first run, you can restart it later with docker start staaash-postgres. If you already have PostgreSQL running another way, just update DATABASE_URL in .env.local.

3. Run pnpm i.

4. Run pnpm db:generate.

5. Run pnpm db:push.

6. Start the web app with pnpm web:dev.

7. Start the worker with pnpm worker:dev.

Resetting Local Data

If you need to reset your local database and file uploads during development:

pnpm app:reset-local-data

This will:

• Delete all local file uploads (.data/files)
• Reset the Prisma database schema with prisma db push --force-reset

Note: Use this script to reset your database please, you may have data remain if you do it manually.

Testing And Quality

• staged files are auto-formatted on commit
• pnpm format:check
• pnpm format for one-off repo-wide formatting or intentional normalization
• pnpm lint
• pnpm test
• pnpm build

AI Use

AI is being used in this project as part of the development and documentation workflow.

That does not change the quality bar. Generated code or generated docs still need to be reviewed, tested, and kept consistent with the repo's actual behavior.

Contributing And Feedback

• read CONTRIBUTING.md before opening work
• use the GitHub issue forms for bug reports and feature requests
• use the PR template when opening changes
• report security problems privately as described in SECURITY.md

Star History

License

AGPL-3.0 — see LICENSE.