stash Documentation

An organizer for your porn, written in Go. Documentation:

12,815 stars Go Go 1 file · ~9,421 tokens #go#golang#graphql#hacktoberfest#json#media#organize#organizer
RAW Doc

1. Project Overview & Quickstart (stashapp/stash)

File: README.md

Stash









Stash is a self-hosted webapp written in Go which organizes and serves your diverse content collection, catering to both your SFW and NSFW needs.

  • Stash gathers information about videos in your collection from the internet, and is extensible through the use of community-built plugins for a large number of content producers and sites.
  • Stash supports a wide variety of both video and image formats.
  • You can tag videos and find them later.
  • Stash provides statistics about performers, tags, studios and more.

You can watch a SFW demo video to see it in action.

For further information see Support & Resources section.

Installing Stash

[!tip]
Step-by-step instructions are available at docs.stashapp.cc/installation.

[!important]
Windows Users

As of version 0.27.0, Stash no longer supports Windows 7, 8, Server 2008 and Server 2012.
At least Windows 10 or Server 2016 is required.

macOS Users

As of version 0.29.0, Stash requires macOS 11 Big Sur or later.
As of version 0.32.0, Stash requires macOS 12 Monterey or later.
Older versions can still be run through Docker.

Windows macOS Linux Docker
Latest Release Development Preview Latest Release Development Preview Latest Release (amd64) Development Preview (amd64) More Architectures... Instructions Sample docker-compose.yml

Download links for other platforms and architectures are available on the Releases page.

First Run

Windows/macOS Users: Security Prompt

On Windows or macOS, running the app might present a security prompt since the application binary isn't yet signed.

  • On Windows, bypass this by clicking "more info" and then the "run anyway" button.
  • On macOS, Control+Click the app, click "Open", and then "Open" again.

ffmpeg

Stash requires FFmpeg. If you don't have it installed, Stash will prompt you to download a copy during setup. It is recommended that Linux users install ffmpeg from their distro's package manager.

Usage

Quickstart Guide

Stash is a web-based application. Once the application is running, the interface is available (by default) from http://localhost:9999.

On first run, Stash will prompt you for some configuration options and media directories to index, called "Scanning" in Stash. After scanning, your media will be available for browsing, curating, editing, and tagging.

Stash can pull metadata (performers, tags, descriptions, studios, and more) directly from many sites through the use of scrapers, which integrate directly into Stash. Identifying an entire collection will typically require a mix of multiple sources:

  • The stashapp team maintains StashDB, a crowd-sourced repository of scene, studio, and performer information. Connecting it to Stash will allow you to automatically identify much of a typical media collection. It runs on our stash-box software and is primarily focused on mainstream digital scenes and studios. Instructions, invite codes, and more can be found in this guide to Accessing StashDB.
  • Several community-managed stash-box databases can also be connected to Stash in a similar manner. Each one serves a slightly different niche and follows their own methodology. A rundown of each stash-box, their differences, and the information you need to sign up can be found in the Metadata Sources section of the documentation.
  • Many community-maintained scrapers can also be downloaded, installed, and updated from within Stash, allowing you to pull data from a wide range of other websites and databases. They can be found by navigating to Settings → Metadata Providers → Available Scrapers → Community (stable). These can be trickier to use than a stash-box because every scraper works a little differently. For more information, please visit the CommunityScrapers repository.
  • All of the above methods of scraping data into Stash are also covered in more detail in our Guide to Scraping.

StashDB is the canonical instance of our open source metadata API, stash-box.

Support & Resources

Need help or want to get involved? Start with the documentation, then reach out to the community if you need further assistance.

Documentation

Community & Discussion

Community Scrapers & Plugins

Architecture

You can find an overview of Stash's architecture in the ARCHITECTURE.md document.

Contributing

We welcome contributions and help from all humans who want to improve the project.

Before contributing, please read the Contributing document to understand our guidelines and processes for contributing to the project.

You can learn about setting up a local development environment in the Development document.

Translation

The widget below shows the current translation status of Stash across all supported languages. If you want to help us translate Stash, you can make an account at Codeberg Translate to contribute to new or existing languages. Thanks!

File: docker/production/README.md

Docker Installation (for most 64-bit GNU/Linux systems)

StashApp is supported on most systems that support Docker. Your OS likely ships with or makes available the necessary packages.

Dependencies

Only docker is required. For the most part your understanding of the technologies can be superficial. So long as you can follow commands and are open to reading a bit, you should be fine.

Installation instructions are available below, and if your distributions's repository ships a current version of docker, you may use that.
https://docs.docker.com/engine/install/

On some distributions, docker compose is shipped separately, usually as docker-cli-compose. docker-compose is not recommended.

Get the docker-compose.yml file

Now you can either navigate to the docker-compose.yml in the repository, or if you have curl, you can make your Linux console do it for you:

text
mkdir stashapp && cd stashapp
curl -o docker-compose.yml https://raw.githubusercontent.com/stashapp/stash/develop/docker/production/docker-compose.yml

Once you have that file where you want it, modify the settings as you please, and then run:

text
docker compose up -d

Installing StashApp this way will by default bind stash to port 9999. This is available in your web browser locally at http://localhost:9999 or on your network as http://YOUR-LOCAL-IP:9999

Good luck and have fun!

Docker

Docker is effectively a cross-platform software package repository. It allows you to ship an entire environment in what's referred to as a container. Containers are intended to hold everything that is needed to run an application from one place to another, making it easy for everyone along the way to reproduce the environment.

The StashApp docker container ships with everything you need to automatically run stash, including ffmpeg.

docker compose

Docker Compose lets you specify how and where to run your containers, and to manage their environment. The docker-compose.yml file in this folder gets you a fully working instance of StashApp exactly as you would need it to have a reasonable instance for testing / developing on. If you are deploying a live instance for production, a reverse proxy (such as NGINX or Traefik) is recommended, but not required.

The latest version is always recommended.

File: docker/compiler/README.md

Modified from https://github.com/bep/dockerfiles/tree/master/ci-goreleaser

When the Dockerfile is changed, the version number should be incremented in .github/workflows/build-compiler.yml and the workflow manually ran. env: COMPILER_IMAGE in .github/workflows/build.yml also needs to be updated to pull the correct image tag.

File: docker/ci/x86_64/README.md

This Dockerfile is used by CI to build the stashapp/stash Docker image. It must be run after cross-compiling - that is, stash-linux must exist in the dist directory. This image must be built from the dist directory.

File: docs/CONTRIBUTING.md

Contributing to Stash

AI Usage Policy

Please see our AI Usage Policy for guidelines on the use of AI in contributions to this project.

Issues

Bug reports and feature requests must use descriptive and concise titles and follow the provided templates. Please use the search function to make sure that you are not submitting duplicates, and that a similar report or request has not already been resolved or rejected.

All issues must be written by humans. Fully AI-generated issues will be closed without comment.

Pull Requests

All pull requests must use descriptive and concise titles and follow the provided templates. In addition, they must follow the the following guidelines:

  • You must link to an open issue that pull request addresses (see GitHub documentation on how to do that).
  • Pull requests must be focused on a single issue or feature. Large, multi-purpose pull requests will be rejected.
  • Large features must be discussed with maintainers before submitting a pull request to ensure it fits with the overall design vision of the project. Failure to do so may result in the pull request being rejected.
  • Pull requests must include code tests that sufficiently cover the changes made.
  • You must detail the manual testing done and describe the steps taken to sufficiently verify the changes.
  • You must be able to explain any line of code and design decision during the review process.
  • You may not have more than 3 open pull requests at a time, unless you have received explicit permission from a maintainer. If you have more than 3 open pull requests, maintainers may ask you to close some of them before they will review any of them.

By submitting a pull request, you agree that you have read and understood and that you are in compliance with the guidelines outlined here, including the AI Usage Policy.

You also agree to license your contribution under the AGPL license, and that all of your previous contributions to the project are also licensed under the AGPL.

Bounties

Pull requests for bounties must be discussed with maintainers before submitting a pull request to ensure it fits with the overall design vision of the project. Failure to do so may result in the pull request being rejected.

Goals and Design Vision

The goal of Stash is to be:

  • An application for organising and viewing NSFW and SFW content - currently this is videos and images, in future this will be extended to include audio and text content
    • Organising includes scraping of metadata from websites and metadata repositories
  • Free and open-source
  • Portable and offline - can be run on a USB stick without needing to install dependencies (with the exception of FFmpeg)
  • Minimal, but highly extensible. The core feature set should be the minimum required to achieve the primary goal, while being extensible enough to extend via plugins
  • Easy to learn and use, with minimal technical knowledge required

The core Stash system is not intended for:

  • Managing downloading of content
  • Managing content on external websites
  • Publicly sharing content

Other requirements:

  • Support as many video and image formats as possible
  • Interfaces with external systems (for example stash-box) should be made as generic as possible.

Design considerations:

  • Features are easy to add and difficult to remove. Large superfluous features should be scrutinised and avoided where possible (e.g. DLNA, filename parser). Such features should be considered for third-party plugins instead.

File: docs/DEVELOPMENT.md

Building from Source

Pre-requisites

Environment

Windows

  1. Download and install Go for Windows
  2. Download and extract MinGW64 (scroll down and select x86_64-posix-seh, don't use the autoinstaller, it doesn't work)
  3. Search for "Advanced System Settings" and open the System Properties dialog.
    1. Click the Environment Variables button
    2. Under System Variables find Path. Edit and add C:\MinGW\bin (replace with the correct path to where you extracted MingW64).

NOTE: The make command in Windows will be mingw32-make with MinGW. For example, make pre-ui will be mingw32-make pre-ui.

macOS

  1. If you don't have it already, install the Homebrew package manager.
  2. Install dependencies: brew install go git gcc make node ffmpeg

Linux

Arch Linux

  1. Install dependencies: sudo pacman -S go git gcc make nodejs ffmpeg --needed

Ubuntu

  1. Install dependencies: sudo apt-get install golang git gcc nodejs ffmpeg -y

OpenBSD

  1. Install dependencies doas pkg_add gmake go git node cmake ffmpeg
  2. Follow the instructions below to build a release, but replace the final step make build-release with gmake flags-release stash, to avoid the PIE buildmode.

NOTE: The make command in OpenBSD will be gmake. For example, make pre-ui will be gmake pre-ui.

Commands

  • make pre-ui - Installs the UI dependencies. This only needs to be run once after cloning the repository, or if the dependencies are updated.
  • make generate - Generates Go and UI GraphQL files. Requires make pre-ui to have been run.
  • make generate-stash-box-client - Generate Go files for the Stash-box client code.
  • make ui - Builds the UI. Requires make pre-ui to have been run.
  • make stash - Builds the stash binary (make sure to build the UI as well... see below)
  • make stash-macapp - Builds the Stash.app macOS app (only works when on macOS, for cross-compilation see below)
  • make phasher - Builds the phasher binary
  • make build - Builds both the stash and phasher binaries, alias for make stash phasher
  • make build-release - Builds release versions (debug information removed) of both the stash and phasher binaries, alias for make flags-release flags-pie build
  • make docker-build - Locally builds and tags a complete 'stash/build' docker image
  • make docker-cuda-build - Locally builds and tags a complete 'stash/cuda-build' docker image
  • make validate - Runs all of the tests and checks required to submit a PR
  • make lint - Runs golangci-lint on the backend
  • make it - Runs all unit and integration tests
  • make fmt - Formats the Go source code
  • make fmt-ui - Formats the UI source code
  • make validate-ui - Runs tests and checks for the UI only
  • make fmt-ui-quick - (experimental) Formats only changed UI source code
  • make validate-ui-quick - (experimental) Runs tests and checks of changed UI code
  • make server-start - Runs a development stash server in the .local directory
  • make server-clean - Removes the .local directory and all of its contents
  • make ui-start - Runs the UI in development mode. Requires a running Stash server to connect to - the server URL can be changed from the default of http://localhost:9999 using the environment variable VITE_APP_PLATFORM_URL, but keep in mind that authentication cannot be used since the session authorization cookie cannot be sent cross-origin. The UI runs on port 3000 or the next available port.

When building, you can optionally prepend flags-* targets to the target list in your make command to use different build flags:

  • flags-release (e.g. make flags-release stash) - Remove debug information from the binary.
  • flags-pie (e.g. make flags-pie build) - Build a PIE (Position Independent Executable) binary. This provides increased security, but it is unsupported on some systems (notably 32-bit ARM and OpenBSD).
  • flags-static (e.g. make flags-static phasher) - Build a statically linked binary (the default is a dynamically linked binary).
  • flags-static-pie (e.g. make flags-static-pie stash) - Build a statically linked PIE binary (using flags-static and flags-pie separately will not work).
  • flags-static-windows (e.g. make flags-static-windows build) - Identical to flags-static-pie, but does not enable the netgo build tag, which is not needed for static builds on Windows.

Local development quickstart

  1. Run make pre-ui to install UI dependencies
  2. Run make generate to create generated files
  3. In one terminal, run make server-start to run the server code
  4. In a separate terminal, run make ui-start to run the UI in development mode
  5. Open the UI in a browser: http://localhost:3000/

⚠️ Note: Running the UI in development mode does not support sending authentication credentials due to issues with cross-origin requests. Ensure credentials are unset on the server when running the UI in development mode.

Changes to the UI code can be seen by reloading the browser page.

Changes to the backend code require a server restart (CTRL-C in the server terminal, followed by make server-start again) to be seen.

On first launch:

  1. On the "Stash Setup Wizard" screen, choose a directory with some files to test with
  2. Press "Next" to use the default locations for the database and generated content
  3. Press the "Confirm" and "Finish" buttons to get into the UI
  4. On the side menu, navigate to "Tasks -> Library -> Scan" and press the "Scan" button
  5. You're all set! Set any other configurations you'd like and test your code changes.

To start fresh with new configuration:

  1. Stop the server (CTRL-C in the server terminal)
  2. Run make server-clean to clear all config, database, and generated files (under .local)
  3. Run make server-start to restart the server
  4. Follow the "On first launch" steps above

Building a release

Simply run make or make release, or equivalently:

  1. Run make pre-ui to install UI dependencies
  2. Run make generate to create generated files
  3. Run make ui to build the frontend
  4. Run make build-release to build a release executable for your current platform

Cross-compiling

This project uses a modification of the CI-GoReleaser Docker container for cross-compilation, defined in docker/compiler/Dockerfile.

To cross-compile the app yourself:

  1. Run make pre-ui, make generate and make ui outside the container, to generate files and build the UI.
  2. Pull the latest compiler image from GHCR: docker pull ghcr.io/stashapp/compiler
  3. Run docker run --rm --mount type=bind,source="$(pwd)",target=/stash -w /stash -it ghcr.io/stashapp/compiler /bin/bash to open a shell inside the container.
  4. From inside the container, run make build-cc-all to build for all platforms, or run make build-cc-{platform} to build for a specific platform (have a look at the Makefile for the list of targets).
  5. You will find the compiled binaries in dist/.

NOTE: Since the container is run as UID 0 (root), the resulting binaries (and the dist/ folder itself, if it had to be created) will be owned by root.

Profiling

Stash can be profiled using the --cpuprofile <output profile filename> command line flag.

The resulting file can then be used with pprof as follows:

go tool pprof

With graphviz installed and in the path, a call graph can be generated with:

go tool pprof -svg > <output svg file>

File: pkg/sqlite/migrations/README.md

Creating a migration

  1. Create new migration file in the migrations directory with the format NN_description.up.sql, where NN is the next sequential number.

  2. Update pkg/sqlite/database.go to update the appSchemaVersion value to the new migration number.

For migrations requiring complex logic or config file changes, see existing custom migrations for examples.

File: pkg/plugin/examples/react-component/README.md

This is a reference React component plugin. It replaces the details part of scene cards with a list of performers and tags.

To build:

  • run pnpm install --frozen-lockfile
  • run npm run build

This will copy the plugin files into the dist directory. These files can be copied to a plugins directory.

File: pkg/plugin/examples/README.md

Building

From the base stash source directory:

text
go build -tags=plugin_example -o plugin_goraw.exe ./pkg/plugin/examples/goraw/...
go build -tags=plugin_example -o plugin_gorpc.exe ./pkg/plugin/examples/gorpc/...

Place the resulting binaries together with the yml files in the plugins subdirectory of your stash directory.

File: scripts/test_db_generator/README.md

This is a quick and dirty go script for generating a contrived database for testing purposes.

Edit the config.yml file to your liking. The numbers indicate the number of objects to generate, the naming section indicates the files from which to generate names.

May cause unexpected behaviour if run against an existing database file.

To run - from the test_db_generator:
go run .

The database file will be generated in the current directory.

2. Official Technical Reference & Guides (stashapp/stash-docs)

File: README.md

Stash-Docs

Website: https://docs.stashapp.cc

Community support

Contributing

Everyone is welcome to help with the documentation. All changes are managed through pull requests.

Read step-by-step guide on how to create a pull request CONTRIBUTING.md.

Local development

Prerequisites

bash
pip install -r requirements.txt

Building the site

  1. Clone the repository and navigate to the project directory.
  2. Run mkdocs serve

License

The documentation site is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.

File: docs/index.md

title: Home
hide:

  • navigation
  • toc

{:target="_blank"}
{:target="_blank"}
{:target="_blank"}
{:target="_blank"}
{:target="_blank"}

Stash{:target="_blank"} is a web application written in Go for serving and organizing your porn collection. It is self-hosted and released under AGPL-3.0 license. Stash currently supports Windows, macOS, Linux, FreeBSD and Docker.

About Stash

  • Stash gathers information about videos in your collection from the internet, and is extensible through the use of community-built plugins for a large number of content producers and sites.
  • Stash supports a wide variety of both video and image formats.
  • You can tag videos and find them later.
  • Stash provides statistics about performers, tags, studios and more.

You can learn more about the software generally via the README{:target="_blank"} on the official repository or via the Stash official website{:target="_blank"}.

Get started

To get started go to Installation and download the latest version for your operating system.

Support

Contribute

  • Spread the word: the more people that know about Stash, the more people can help with the tasks below.
  • Help other users: we got new users coming in all the time that need assistance. Stopping in help channels/rooms now and again to assist can save developers some time.
  • Write documentation: help to improve the Stash documentation.
  • Contribute to the website: the website could definitely use some attention.
  • Find bugs: test the software for bugs and create GitHub issues for them to help developers confirm and fix them faster.
  • Write scrapers: if there is a site that isn't being scraped properly or at all, head on over to scrapers channel/room and see if you can't help scrape some metadata from a site.
  • Populate StashDB: StashDB is our canonical database where we store metadata and hashes. You can submit info from your Stash instance to the database or just help to improve the already existing information.
  • Support financially: Stash development runs on donations. Donations are collected through OpenCollective{:target="_blank"}. You can do anonymous one-time donations or recurring donations.
  • Sponsor on GitHub: You can sponsor the stashapp organization on GitHub{:target="_blank"} via one-time or monthly donation.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#go Browse go catalog → #golang Browse golang catalog → #graphql Browse graphql catalog → #hacktoberfest Browse hacktoberfest catalog → #json Browse json catalog → #media Browse media catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →