Stash-box

To enable distance matching for pHashes, you must install the pg-spgist_hamming Postgres extension.

If you install the extension after the initial database migrations have already run, you must manually run migration #14 to install the extension and add the necessary index. Alternatively, you can wipe the database and let the migrations run from scratch upon the next start.

To create a static bundle suitable for use with the Go server, run the build command.

pnpm build

Stash-box supports macOS, Windows, and Linux.

Linux Prerequisites

To build from source on Linux, you must install:

• libvips
• gcc

Build and Run

1. Build the application using make.
2. Ensure a PostgreSQL database is available.
3. Run the executable. If no configuration file is found, it will generate stash-box-config.yml in the current directory.

To build an executable for your current platform, follow these steps:

1. Run make generate to ensure any changed Go GraphQL files are updated.
2. Run make ui build to compile the UI and build the binary.

To run the frontend locally, you must first initialize your environment configuration and provide an API key.

1. Copy the local shadow environment file: cp .env.development.local.shadow .env.development.local.
2. Open .env.development.local and set the VITE_APIKEY variable to your user's API key.
3. Start the server with pnpm start.

By default, the server runs at http://localhost:3001. To change the port, uncomment the PORT entry in .env.development.local and set your desired value.

To use HTTPS with self-signed certificates, generate a certificate and key pair using OpenSSL.

Once generated, you must name the files exactly stash-box.crt and stash-box.key and place them in the same directory as the stash-box binary. When these files are detected, Stash-box will automatically switch from HTTP to HTTPS.

openssl req -x509 -newkey rsa:4096 -sha256 -days 7300 -nodes -keyout stash-box.key -out stash-box.crt -extensions san -config <(echo "[req]"; echo "distinguished_name=req"; echo "[san]"; echo "subjectAltName=DNS:stash-box.server,IP:127.0.0.1") -subj /CN=stash-box.server

Use the following commands to maintain code quality:

• Linting: pnpm lint runs the linter.
• Formatting: pnpm format runs the code formatter.
• Validation: pnpm validate runs a full validation suite (recommended before submitting a Pull Request).

To run the frontend in development mode, navigate to the frontend directory and run pnpm start.

To avoid manual login during development, you can set the API key in frontend/.env.development.local. This is required if is_production is enabled on the server, or if the server uses HTTPS or a custom port. Refer to frontend/.env.development.local.shadow for configuration examples.

You can deploy stash-box using Docker. A production-ready docker-compose configuration is available in the repository. If you already have a PostgreSQL instance running, you can use the official image from Docker Hub to install stash-box standalone.

• Production Compose: docker/production/docker-compose.yml (Note: You can omit Traefik if a reverse proxy is not required).
• Docker Hub: stashapp/stash-box

docker pull stashapp/stash-box

On the first successful run, stash-box performs schema migrations and generates a root user.

Important: The root user's random password and API key are printed once to stdout and are not logged. You must capture the console output during the first run to retrieve these credentials.

If you lose the credentials, you can force the creation of a new root user by deleting the root user row from the database and restarting the application.