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 into the same folder. Use the latest release, or pick a specific version if you need one. Files on main may include unreleased changes.

2. Rename example.env to .env, open it, set DB_PASSWORD to a secure value (you can use something like pwgen), and change any other values you want.

3. 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.

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

docker compose pull
docker compose up -d

Migrations run automatically on startup.

Postgres major upgrades need extra care. Fresh installs use Postgres 18. Do not point the Postgres 18 container at an old Postgres 16 postgres folder by only changing the image tag. To keep beta data across this baseline change, use the Postgres 18 upgrade path in docs/operations/backup-restore.md.

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.