2019-02-09 12:30:49 +00:00
# Stash
2019-02-15 00:31:48 +00:00
[](https://goreportcard.com/report/github.com/stashapp/stash)
2019-03-24 00:13:55 +00:00
[](https://discord.gg/2TsNFKt)
2019-02-10 17:33:18 +00:00
2020-07-08 03:05:55 +00:00
https://stashapp.cc
2021-03-11 04:56:22 +00:00
**Stash is a locally hosted web-based app written in Go which organizes and serves your porn.**
2019-02-09 12:30:49 +00:00
2021-05-03 02:49:15 +00:00
* It can gather 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.
* It supports a wide variety of both video and image formats.
2021-03-11 04:56:22 +00:00
* You can tag videos and find them later.
* It provides statistics about performers, tags, studios and other things.
2019-02-09 12:30:49 +00:00
2021-05-05 04:14:39 +00:00
You can [watch a SFW demo video ](https://vimeo.com/545323354 ) to see it in action.
2020-07-01 22:45:14 +00:00
2021-05-03 02:49:15 +00:00
For further information you can [read the in-app manual ](ui/v2.5/src/docs/en ).
2021-03-11 04:56:22 +00:00
# Installing stash
2021-05-03 02:49:15 +00:00
## via Docker
2019-04-28 17:52:21 +00:00
Follow [this README.md in the docker directory. ](docker/production/README.md )
2021-03-11 04:56:22 +00:00
## Pre-Compiled Binaries
2019-02-09 12:30:49 +00:00
2021-05-03 02:49:15 +00:00
The Stash server runs on macOS, Windows, and Linux. Download the [latest release here ](https://github.com/stashapp/stash/releases ).
2019-02-10 02:01:00 +00:00
2020-01-25 03:35:55 +00:00
Run the executable (double click the exe on windows or run `./stash-osx` / `./stash-linux` from the terminal on macOS / Linux) and navigate to either https://localhost:9999 or http://localhost:9999 to get started.
2019-02-10 02:01:00 +00:00
2021-05-03 02:49:15 +00:00
*Note for Windows users:* Running the app might present a security prompt since the binary isn't yet signed. Bypass this by clicking "more info" and then the "run anyway" button.
2019-02-10 02:01:00 +00:00
2019-02-11 06:39:21 +00:00
#### FFMPEG
If stash is unable to find or download FFMPEG then download it yourself from the link for your platform:
2021-04-16 06:20:20 +00:00
* [macOS ffmpeg ](https://evermeet.cx/ffmpeg/ffmpeg-4.3.1.zip ), [macOS ffprobe ](https://evermeet.cx/ffmpeg/ffprobe-4.3.1.zip )
* [Windows ](https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.zip )
* [Linux ](https://www.johnvansickle.com/ffmpeg/ )
2019-02-11 06:39:21 +00:00
The `ffmpeg(.exe)` and `ffprobe(.exe)` files should be placed in `~/.stash` on macOS / Linux or `C:\Users\YourUsername\.stash` on Windows.
2019-04-11 17:55:58 +00:00
# Usage
2021-03-11 04:56:22 +00:00
## Quickstart Guide
1) Download and install Stash and its dependencies
2) Run Stash. It will prompt you for some configuration options and a directory to index (you can also do this step afterward)
3) After configuration, launch your web browser and navigate to the URL shown within the Stash app.
2021-05-03 02:49:15 +00:00
**Note that Stash does not currently retrieve and organize information about your entire library automatically.** You will need to help it along through the use of [scrapers ](blob/develop/ui/v2.5/src/docs/en/Scraping.md ). The Stash community has developed scrapers for many popular data sources which can be downloaded and installed from [this repository ](https://github.com/stashapp/CommunityScrapers ).
2021-03-11 04:56:22 +00:00
2021-05-03 02:49:15 +00:00
The simplest way to tag a large number of files is by using the [Tagger ](https://github.com/stashapp/stash/blob/develop/ui/v2.5/src/docs/en/Tagger.md ) which uses filename keywords to help identify the file and pull in scene and performer information from our stash-box database. Note that this data source is not comprehensive and you may need to use the scrapers to identify some of your media.
2021-03-11 04:56:22 +00:00
2019-04-11 17:55:58 +00:00
## CLI
2021-03-11 04:56:22 +00:00
Stash runs as a command-line app and local web server. There are some command-line options available, which you can see by running `stash --help` .
2019-04-11 17:55:58 +00:00
For example, to run stash locally on port 80 run it like this (OSX / Linux) `stash --host 127.0.0.1 --port 80`
## SSL (HTTPS)
2021-05-03 02:49:15 +00:00
Stash can run over HTTPS with some additional work. First you must generate a SSL certificate and key combo. Here is an example using openssl:
2019-04-11 17:55:58 +00:00
`openssl req -x509 -newkey rsa:4096 -sha256 -days 7300 -nodes -keyout stash.key -out stash.crt -extensions san -config <(echo "[req]"; echo distinguished_name=req; echo "[san]"; echo subjectAltName=DNS:stash.server,IP:127.0.0.1) -subj /CN=stash.server`
2019-04-28 17:52:21 +00:00
This command would need customizing for your environment. [This link ](https://stackoverflow.com/questions/10175812/how-to-create-a-self-signed-certificate-with-openssl ) might be useful.
2019-04-11 17:55:58 +00:00
2021-08-31 09:37:45 +00:00
Once you have a certificate and key file name them `stash.crt` and `stash.key` and place them in the same directory as the `config.yml` file, or the `~/.stash` directory. Stash detects these and starts up using HTTPS rather than HTTP.
2019-04-11 17:55:58 +00:00
2021-09-21 04:12:10 +00:00
## Basepath rewriting
The basepath defaults to `/` . When running stash via a reverse proxy in a subpath, the basepath can be changed by having the reverse proxy pass `X-Forwarded-Prefix` (and optionally `X-Forwarded-Port` ) headers. When detects these headers, it alters the basepath URL of the UI.
2021-03-11 04:56:22 +00:00
# Customization
2021-05-03 02:49:15 +00:00
## Themes and CSS Customization
There is a [directory of community-created themes ](https://github.com/stashapp/stash/wiki/Themes ) on our Wiki, along with instructions on how to install them.
2019-02-11 10:49:39 +00:00
2021-05-03 02:49:15 +00:00
You can also make Stash interface fit your desired style with [Custom CSS snippets ](https://github.com/stashapp/stash/wiki/Custom-CSS-snippets ) and [CSS Tweaks ](https://github.com/stashapp/stash/wiki/CSS-Tweaks ).
2019-04-20 17:32:01 +00:00
2021-03-31 04:55:15 +00:00
# Support (FAQ)
2019-04-20 17:32:01 +00:00
2021-05-03 02:49:15 +00:00
Answers to other Frequently Asked Questions can be found [on our Wiki ](https://github.com/stashapp/stash/wiki/FAQ )
2019-03-24 00:13:55 +00:00
2021-03-11 04:56:22 +00:00
For issues not addressed there, there are a few options.
2019-02-09 12:30:49 +00:00
2021-03-11 04:56:22 +00:00
* Read the [Wiki ](https://github.com/stashapp/stash/wiki )
* Check the in-app documentation (also available [here ](https://github.com/stashapp/stash/tree/develop/ui/v2.5/src/docs/en )
2021-05-03 02:49:15 +00:00
* Join the [Discord server ](https://discord.gg/2TsNFKt ), where the community can offer support.
2021-03-11 04:56:22 +00:00
2021-05-03 02:49:15 +00:00
# Compiling From Source Code
2019-02-09 12:30:49 +00:00
2021-05-03 02:49:15 +00:00
## Pre-requisites
2019-02-14 22:53:32 +00:00
2019-11-28 15:40:24 +00:00
* [Go ](https://golang.org/dl/ )
Add golangci-lint workflow (#1759)
* Add golangci-lint workflow
* Add a bit more lenient linter timeout
1 Minute isn't always enough, so bump to 3.
* Document golangci, add make target
Document how to get golangci-lint in the README file. While here,
provide a QOL target in the makefile
for the linter, and make it part of validation.
* Introduce .golangci.yml
This is the default golangci-lint configuration file location. Use it.
Move configuration into the yaml file, and enable the default set of
linters; we know we pass most of those.
* Add gofmt and revive to golangci-lint
Read the golangci-lint source code to figure out the configuration format.
Copy the configuration from `revive.toml` into the linter configuration.
* Do not set simplify on gofmt
The project currently runs without simplify. So for consistency, don't
make that a requirement for the linter.
* Add new-from-rev
Older issues should not be considered a failure for new PRs and issues.
Use new-from-from to make the current develop as the point-in-time for
when we consider errors.
Once in the tree, we can go and fix the older errors in separate
patches, taking a little bit at a time.
* Move to golangci-lint
Rewrite the way we run targets in the makefile, so it is split between
frontend and backend.
Use the frontend build steps in build.yml
Update README to reflect the new world order.
* Remove check-gofmt.sh
The tool now runs as part of golangci-lint, in particular through the
'validate' target in the Makefile.
* Remove targets for golangci-lint
Fold these targets into the `lint` target. While here, update README.
2021-09-27 00:41:59 +00:00
* [GolangCI ](https://golangci-lint.run/ ) - A meta-linter which runs several linters in parallel
* To install, follow the [local installation instructions ](https://golangci-lint.run/usage/install/#local-installation )
2019-03-23 22:40:23 +00:00
* [Yarn ](https://yarnpkg.com/en/docs/install ) - Yarn package manager
Add golangci-lint workflow (#1759)
* Add golangci-lint workflow
* Add a bit more lenient linter timeout
1 Minute isn't always enough, so bump to 3.
* Document golangci, add make target
Document how to get golangci-lint in the README file. While here,
provide a QOL target in the makefile
for the linter, and make it part of validation.
* Introduce .golangci.yml
This is the default golangci-lint configuration file location. Use it.
Move configuration into the yaml file, and enable the default set of
linters; we know we pass most of those.
* Add gofmt and revive to golangci-lint
Read the golangci-lint source code to figure out the configuration format.
Copy the configuration from `revive.toml` into the linter configuration.
* Do not set simplify on gofmt
The project currently runs without simplify. So for consistency, don't
make that a requirement for the linter.
* Add new-from-rev
Older issues should not be considered a failure for new PRs and issues.
Use new-from-from to make the current develop as the point-in-time for
when we consider errors.
Once in the tree, we can go and fix the older errors in separate
patches, taking a little bit at a time.
* Move to golangci-lint
Rewrite the way we run targets in the makefile, so it is split between
frontend and backend.
Use the frontend build steps in build.yml
Update README to reflect the new world order.
* Remove check-gofmt.sh
The tool now runs as part of golangci-lint, in particular through the
'validate' target in the Makefile.
* Remove targets for golangci-lint
Fold these targets into the `lint` target. While here, update README.
2021-09-27 00:41:59 +00:00
* Run `yarn install --frozen-lockfile` in the `stash/ui/v2.5` folder (before running make generate for first time).
2019-02-14 22:53:32 +00:00
2019-07-27 20:11:51 +00:00
NOTE: You may need to run the `go get` commands outside the project directory to avoid modifying the projects module file.
2019-02-10 01:07:39 +00:00
## Environment
### macOS
TODO
### Windows
1. Download and install [Go for Windows ](https://golang.org/dl/ )
2. Download and install [MingW ](https://sourceforge.net/projects/mingw-w64/ )
3. Search for "advanced system settings" and open the system properties dialog.
2019-04-28 17:52:21 +00:00
1. Click the `Environment Variables` button
2021-09-08 05:30:15 +00:00
2. Under system variables find the `Path` . Edit and add `C:\Program Files\mingw-w64\*\mingw64\bin` (replace * with the correct path).
2019-02-10 01:07:39 +00:00
2019-11-28 15:40:24 +00:00
NOTE: The `make` command in Windows will be `mingw32-make` with MingW.
2019-02-10 01:07:39 +00:00
## Commands
2019-02-09 12:30:49 +00:00
2020-04-29 02:13:08 +00:00
* `make generate` - Generate Go and UI GraphQL files
2019-07-27 20:11:51 +00:00
* `make build` - Builds the binary (make sure to build the UI as well... see below)
2021-09-08 05:30:15 +00:00
* `make docker-build` - Locally builds and tags a complete 'stash/build' docker image
2020-04-29 02:13:08 +00:00
* `make pre-ui` - Installs the UI dependencies. Only needs to be run once before building the UI for the first time, or if the dependencies are updated
2021-09-22 03:08:34 +00:00
* `make fmt-ui` - Formats the UI source code
* `make ui` - Builds the frontend
Add golangci-lint workflow (#1759)
* Add golangci-lint workflow
* Add a bit more lenient linter timeout
1 Minute isn't always enough, so bump to 3.
* Document golangci, add make target
Document how to get golangci-lint in the README file. While here,
provide a QOL target in the makefile
for the linter, and make it part of validation.
* Introduce .golangci.yml
This is the default golangci-lint configuration file location. Use it.
Move configuration into the yaml file, and enable the default set of
linters; we know we pass most of those.
* Add gofmt and revive to golangci-lint
Read the golangci-lint source code to figure out the configuration format.
Copy the configuration from `revive.toml` into the linter configuration.
* Do not set simplify on gofmt
The project currently runs without simplify. So for consistency, don't
make that a requirement for the linter.
* Add new-from-rev
Older issues should not be considered a failure for new PRs and issues.
Use new-from-from to make the current develop as the point-in-time for
when we consider errors.
Once in the tree, we can go and fix the older errors in separate
patches, taking a little bit at a time.
* Move to golangci-lint
Rewrite the way we run targets in the makefile, so it is split between
frontend and backend.
Use the frontend build steps in build.yml
Update README to reflect the new world order.
* Remove check-gofmt.sh
The tool now runs as part of golangci-lint, in particular through the
'validate' target in the Makefile.
* Remove targets for golangci-lint
Fold these targets into the `lint` target. While here, update README.
2021-09-27 00:41:59 +00:00
* `make lint` - Run the linter on the backend
2020-04-29 02:13:08 +00:00
* `make fmt` - Run `go fmt`
* `make it` - Run the unit and integration tests
* `make validate` - Run all of the tests and checks required to submit a PR
2021-05-24 05:44:40 +00:00
* `make ui-start` - Runs the UI in development mode. Requires a running stash server to connect to. Stash port can be changed from the default of `9999` with environment variable `REACT_APP_PLATFORM_PORT` .
2019-02-09 12:30:49 +00:00
2019-02-10 01:07:39 +00:00
## Building a release
2019-02-09 12:30:49 +00:00
Add golangci-lint workflow (#1759)
* Add golangci-lint workflow
* Add a bit more lenient linter timeout
1 Minute isn't always enough, so bump to 3.
* Document golangci, add make target
Document how to get golangci-lint in the README file. While here,
provide a QOL target in the makefile
for the linter, and make it part of validation.
* Introduce .golangci.yml
This is the default golangci-lint configuration file location. Use it.
Move configuration into the yaml file, and enable the default set of
linters; we know we pass most of those.
* Add gofmt and revive to golangci-lint
Read the golangci-lint source code to figure out the configuration format.
Copy the configuration from `revive.toml` into the linter configuration.
* Do not set simplify on gofmt
The project currently runs without simplify. So for consistency, don't
make that a requirement for the linter.
* Add new-from-rev
Older issues should not be considered a failure for new PRs and issues.
Use new-from-from to make the current develop as the point-in-time for
when we consider errors.
Once in the tree, we can go and fix the older errors in separate
patches, taking a little bit at a time.
* Move to golangci-lint
Rewrite the way we run targets in the makefile, so it is split between
frontend and backend.
Use the frontend build steps in build.yml
Update README to reflect the new world order.
* Remove check-gofmt.sh
The tool now runs as part of golangci-lint, in particular through the
'validate' target in the Makefile.
* Remove targets for golangci-lint
Fold these targets into the `lint` target. While here, update README.
2021-09-27 00:41:59 +00:00
1. Run `make generate` to create generated files
2019-10-15 15:03:01 +00:00
2. Run `make ui` to compile the frontend
3. Run `make build` to build the executable for your current platform
2019-02-09 12:30:49 +00:00
2019-02-14 22:53:32 +00:00
## Cross compiling
2019-02-09 12:30:49 +00:00
2021-05-03 02:49:15 +00:00
This project uses a modification of the [CI-GoReleaser ](https://github.com/bep/dockerfiles/tree/master/ci-goreleaser ) docker container to create an environment
2019-04-28 17:52:21 +00:00
where the app can be cross-compiled. This process is kicked off by CI via the `scripts/cross-compile.sh` script. Run the following
2019-02-14 22:53:32 +00:00
command to open a bash shell to the container to poke around:
2019-02-10 12:16:29 +00:00
2019-03-23 22:40:23 +00:00
`docker run --rm --mount type=bind,source="$(pwd)",target=/stash -w /stash -i -t stashappdev/compiler:latest /bin/bash`
2021-05-16 07:21:11 +00:00
## Profiling
Stash can be profiled using the `--cpuprofile <output profile filename>` command line flag.
Add golangci-lint workflow (#1759)
* Add golangci-lint workflow
* Add a bit more lenient linter timeout
1 Minute isn't always enough, so bump to 3.
* Document golangci, add make target
Document how to get golangci-lint in the README file. While here,
provide a QOL target in the makefile
for the linter, and make it part of validation.
* Introduce .golangci.yml
This is the default golangci-lint configuration file location. Use it.
Move configuration into the yaml file, and enable the default set of
linters; we know we pass most of those.
* Add gofmt and revive to golangci-lint
Read the golangci-lint source code to figure out the configuration format.
Copy the configuration from `revive.toml` into the linter configuration.
* Do not set simplify on gofmt
The project currently runs without simplify. So for consistency, don't
make that a requirement for the linter.
* Add new-from-rev
Older issues should not be considered a failure for new PRs and issues.
Use new-from-from to make the current develop as the point-in-time for
when we consider errors.
Once in the tree, we can go and fix the older errors in separate
patches, taking a little bit at a time.
* Move to golangci-lint
Rewrite the way we run targets in the makefile, so it is split between
frontend and backend.
Use the frontend build steps in build.yml
Update README to reflect the new world order.
* Remove check-gofmt.sh
The tool now runs as part of golangci-lint, in particular through the
'validate' target in the Makefile.
* Remove targets for golangci-lint
Fold these targets into the `lint` target. While here, update README.
2021-09-27 00:41:59 +00:00
The resulting file can then be used with pprof as follows:
2021-05-16 07:21:11 +00:00
`go tool pprof <path to binary> <path to profile filename>`
With `graphviz` installed and in the path, a call graph can be generated with:
`go tool pprof -svg <path to binary> <path to profile filename> > <output svg file>`
