Stash

https://github.com/stashapp/stash-docs
Admin
Stash is a media manager for adult content, providing features for organizing, browsing, and...
Tokens:28,869
Snippets:308
Trust Score:-
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Enable and start stash service

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/synology.md

Enable and start the stash service using systemctl.

```bash
sudo systemctl enable "$(pwd)/stash.service"
sudo systemctl start stash.service
```

--------------------------------

### Enable Stash service at boot

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Sets stash_enable=YES via sysrc so Stash starts when the jail boots.

```shell
sysrc "stash_enable=YES"
```

--------------------------------

### Install Python dependencies for scrapers and plugins

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/synology.md

Run these commands from the stash user home directory to scan all scrapers and plugins for dependencies and install them. Using pipreqs scans all installed scrapers and plugins to find required dependencies; alternatively, you can run pip3 install -r requirements.txt in each individual directory.

```bash
pipreqs .stash/.
pip3 install -r .stash/requirements.txt
```

--------------------------------

### Set up Python environment for Stash

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/synology.md

Prepare a Python environment for scrapers and plugins by ensuring pip, creating a virtual environment, activating it, and installing pipreqs.

```bash
python3.11 -m ensurepip --upgrade
python3.11 -m venv stash-env
source stash-env/bin/activate
pip3 install pipreqs
```

--------------------------------

### Install Python dependencies with pip

Source: https://github.com/stashapp/stash-docs/blob/main/README.md

Install the required Python modules listed in requirements.txt using pip. This is a prerequisite for local development.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install ffmpeg in iocage jail

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Installs ffmpeg (and ffprobe) via pkg inside the iocage jail, required for video processing.

```shell
pkg install ffmpeg
```

--------------------------------

### Launch Chrome with remote debugging

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/scraping-metadata-behind-login.md

Run this command in your console from the Chrome binary directory to start the instance that Stash will control.

```bash
chrome.exe --remote-debugging-port=9222
```

--------------------------------

### Start Stash service

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Starts the Stash service immediately. After this, Stash is available at http://jail-IP:9999/.

```shell
service stash start
```

--------------------------------

### Extract video sample with ffmpeg

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/troubleshooting-video-playback.md

Extract a 30-second sample starting at the 120-second marker, copying video and audio streams without re-encoding. Useful for providing a sample to developers for analysis.

```shell
ffmpeg -ss 120 -i big_buck_bunny.mkv  -t 30 -c:v copy -c:a copy 30_second_sample.mkv
```

--------------------------------

### Apache reverse proxy for Stash

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/reverse-proxy.md

Apache reverse proxy configuration for Stash under the `/stash` path. Includes commented-out directives for WebSocket support on Apache < 2.4.47 and SSL setup.

```bash
# if using apache < 2.4.47, remove upgrade=websocket
ProxyPass "/stash" "http://127.0.0.1:9999" upgrade=websocket
ProxyPassReverse "/stash" "http://127.0.0.1:9999"
RequestHeader setIfEmpty X-Forwarded-Prefix "/stash"
ProxyPreserveHost on

# for name resolution
ServerAdmin admin@example.com
ServerName example.com
ServerAlias stash.example.com

# to enable websockets for apache < 2.4.47
#RewriteEngine on
#RewriteCond %{HTTP:Upgrade} websocket [NC]
#RewriteCond %{HTTP:Connection} upgrade [NC]
#RewriteRule ^/?stash/(.*) "ws://127.0.0.1:9999/$1" [P,L]

# to add SSL
SSLEngine on
SSLCertificateFile /path/to/cert.pem
SSLCertificateKeyFile /path/to/cert.key
```

--------------------------------

### Create rc.d startup script directory and file

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Creates /usr/local/etc/rc.d and opens the stash script in the ee editor. The script content is entered in the editor and then made executable.

```shell
mkdir /usr/local/etc/rc.d
ee /usr/local/etc/rc.d/stash
```

```shell
#!/bin/sh

# PROVIDE: stash
# REQUIRE: DAEMON
# KEYWORD: shutdown


. /etc/rc.subr

name=stash
rcvar=stash_enable

load_rc_config $name

: ${stash_enable:="NO"}
: ${stash_user:="stash"}
: ${stash_group:="stash"}
: ${stash_config_dir:="/usr/local/etc/stash/config.yml"}
: ${stash_exec_bin:="/usr/local/bin/stash-linux"}

#daemon
pidfile="/var/run/${name}.pid"
command="/usr/sbin/daemon"
command_args="-f -P ${pidfile} ${stash_exec_bin} --config ${stash_config_dir}"
start_precmd="stash_precmd"

stash_precmd() {
    install -o ${stash_user} -g ${stash_group} /dev/null ${pidfile}
}

run_rc_command $1
```

--------------------------------

### Create .profile for Stash

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/synology.md

Create a .profile file that adds /usr/local/bin to PATH and activates the stash-env virtual environment on login.

```bash
echo 'PATH=/usr/local/bin:$PATH' > .profile
echo 'source stash-env/bin/activate' >> .profile
```

--------------------------------

### Open the Stash SQLite3 database with sqlite3 client

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/manually-editing-the-stash-sqlite3-database.md

Navigate to the ~/.stash directory and open the stash-go.sqlite database using the sqlite3 client. This is the first step before making any manual edits.

```bash
cd ~/.stash
sqlite3 stash-go.sqlite
```

--------------------------------

### Link ffprobe and ffmpeg

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/synology.md

Create symbolic links for ffprobe and ffmpeg from the ffmpeg7 package to /usr/local/bin so they are accessible in the PATH.

```bash
sudo ln -sf /var/packages/ffmpeg7/target/bin/ffprobe /usr/local/bin/ffprobe
sudo ln -sf /var/packages/ffmpeg7/target/bin/ffmpeg /usr/local/bin/ffmpeg
```

--------------------------------

### Create configuration directory

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Creates /usr/local/etc/stash for Stash's config file, database, and other data, and sets ownership to the stash user.

```shell
mkdir /usr/local/etc/stash
chown stash:stash /usr/local/etc/stash
```

--------------------------------

### Create stash.service systemd unit

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/synology.md

Systemd service file to run Stash at startup. Change the ExecStart line to match the exact name of the downloaded stash executable.

```ini
[Unit]
Description=Run Stash at startup
After=network.target

[Service]
WorkingDirectory=/var/services/homes/stash
Type=simple
User=stash
ExecStart=/bin/bash -c -l '\
   exec ./stash-linux'
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Apache prerequisites for reverse proxy

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/reverse-proxy.md

Prerequisite Apache modules to enable for the reverse proxy configuration. Includes modules for proxying, rewriting, headers, and SSL.

```bash
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_balancer
sudo a2enmod lbmethod_byrequests

sudo a2enmod rewrite
sudo a2enmod headers

# for SSL
sudo a2enmod ssl
```

--------------------------------

### Download and verify Stash binary

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/synology.md

Download the correct Stash binary for your Synology architecture, download the SHA1 checksum, validate it, and clean up. The expected output is `stash-linux: OK`; otherwise the download failed.

```bash
# find what architecture your Synology is running on
uname -m

# depending on the architecture, you'll have to download the right version of stash

# x86_64
wget https://github.com/stashapp/stash/releases/latest/download/stash-linux
# armv6l
wget https://github.com/stashapp/stash/releases/latest/download/stash-linux-arm32v6
# armv7l
wget https://github.com/stashapp/stash/releases/latest/download/stash-linux-arm32v7
# aarch64
wget https://github.com/stashapp/stash/releases/latest/download/stash-linux-arm64v8

# Download the CHECKSUM
wget https://github.com/stashapp/stash/releases/latest/download/CHECKSUMS_SHA1

# Perform the checksum validation
sha1sum -c --ignore-missing CHECKSUMS_SHA1

# you should see a line that says `stash-linux: OK`
# if not, something went wrong during the download

# Clean up the now unnecessary file
rm CHECKSUMS_SHA1
```

--------------------------------

### Download stash-linux binary

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Downloads the stash-linux binary from GitHub release v0.22.1 into /usr/local/bin, then sets ownership to stash and makes it executable.

```shell
cd /usr/local/bin
fetch https://github.com/stashapp/stash/releases/download/v0.22.1/stash-linux
chown stash:stash stash-linux
chmod +x stash-linux
```

--------------------------------

### Inspect video file with ffprobe

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/troubleshooting-video-playback.md

Use ffprobe to inspect a video file's format and stream information. This is useful when filing bug reports or discussing playback issues in chat.

```shell
ffprobe -show_format -show_streams big_buck_bunny.mkv
```

--------------------------------

### POST /login

Source: https://github.com/stashapp/stash-docs/blob/main/docs/api.md

Legacy cookie authentication endpoint. Used for configurations with username/password. Obsolete since v0.7, use API key authentication instead.

```APIDOC
## [POST] /login

### Description
This endpoint is used for legacy cookie authentication. It is obsolete since version v0.7 and is only for configurations using a username/password.

### Method
POST

### Endpoint
`<server>:<port>/login`

### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
```shell
curl --verbose --cookie-jar cookie.txt --data 'username=stash&password=**' localhost:9999/login
```

### Response
Sets a cookie for subsequent requests. The cookie must be included in subsequent GraphQL requests.

### Error Handling
If authentication fails, an error will be returned.
```

--------------------------------

### Enable Linux compatibility in jail rc.conf

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Adds enable_linux="YES" to /etc/rc.conf inside the iocage jail to allow the stash-linux binary to run on FreeBSD. Requires also setting the linux_enable tunable in the TrueNAS Web UI and rebooting the system.

```shell
enable_linux="YES"
```

--------------------------------

### Connect to NAS via SSH

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/synology.md

Connect to the NAS via SSH using the newly created stash account that is part of the administrators group.

```bash
ssh stash@your_nas_hostname
```

--------------------------------

### Nginx reverse proxy with external_host

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/reverse-proxy.md

Nginx configuration using `stash.home` as the domain and `192.168.0.1` as Stash's IP. The `external_host` configuration option should be set to `http://stash.home`.

```bash
server {
    listen 80;
    listen [::]:80;

    server_name stash.home;
    client_max_body_size 0;

    location / {
        proxy_pass http://192.168.0.1:9999;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

--------------------------------

### Nginx + Docker (Linuxserver Letsencrypt) reverse proxy for Stash

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/reverse-proxy.md

Nginx configuration for use with the linuxserver letsencrypt Docker container. Place this in a `stash.subdomain.conf` file in the `proxy-confs` folder. Includes commented-out options for HTTP and LDAP authentication.

```bash
# make sure that your dns has a cname set for stash

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name stash.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    # enable for ldap auth, fill in ldap details in ldap.conf
    #include /config/nginx/ldap.conf;

    location / {
        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable the next two lines for ldap auth
        #auth_request /auth;
        #error_page 401 =200 /login;

        include /config/nginx/proxy.conf;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        resolver 127.0.0.11 valid=30s;
        set $upstream_app stash;
        set $upstream_port 9999;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
        proxy_set_header Host $http_host;
        proxy_read_timeout 60000s;
    }
}
```

--------------------------------

### Docker Compose configuration for stashapp/stash

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/docker.md

Docker Compose configuration for running the official stashapp/stash image. Sets the container port to 9999, configures storage volumes for config, data, metadata, cache, blobs, and generated content, and includes logging options. Uncomment network_mode: host to use DLNA functionality.

```yaml
# APPNICENAME=Stash
# APPDESCRIPTION=An organizer for your porn, written in Go
services:
  stash:
    image: stashapp/stash:latest
    container_name: stash
    restart: unless-stopped
    ## the container's port must be the same with the STASH_PORT in the environment section
    ports:
      - "9999:9999"
    ## If you intend to use stash's DLNA functionality uncomment the below network mode and comment out the above ports section
    # network_mode: host
    logging:
      driver: "json-file"
      options:
        max-file: "10"
        max-size: "2m"
    environment:
      - STASH_STASH=/data/
      - STASH_GENERATED=/generated/
      - STASH_METADATA=/metadata/
      - STASH_CACHE=/cache/
      ## Adjust below to change default port (9999)
      - STASH_PORT=9999
    volumes:
      - /etc/localtime:/etc/localtime:ro
      ## Adjust below paths (the left part) to your liking.
      ## E.g. you can change ./config:/root/.stash to ./stash:/root/.stash
      ## The left part is the path on your host, the right part is the path in the stash container.

      ## Keep configs, scrapers, and plugins here.
      - ./config:/root/.stash
      ## Point this at your collection.
      ## The left side is where your collection is on your host, the right side is where it will be in stash.
      - ./data:/data
      ## This is where your stash's metadata lives
      - ./metadata:/metadata
      ## Any other cache content.
      - ./cache:/cache
      ## Where to store binary blob data (scene covers, images)
      - ./blobs:/blobs
      ## Where to store generated content (screenshots,previews,transcodes,sprites)
      - ./generated:/generated
```

--------------------------------

### Create stash user

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Creates a non-login user named stash with UID 1069 and home directory /nonexistent, used to run the Stash service instead of root.

```shell
pw useradd -n stash -u 1069 -d /nonexistent -s /usr/sbin/nologin
```

--------------------------------

### Configure scraper for CDP

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/scraping-metadata-behind-login.md

Add this setting to your scraper's .yml file to enable Chrome DevTools Protocol support.

```yaml
driver:
  useCDP: true
```

--------------------------------

### Websocket proxy headers for 422 errors

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/reverse-proxy.md

Add these lines to the server block in the proxy.conf file to fix websocket 422 errors. This configures the proxy to use HTTP/1.1 and pass the Upgrade and Connection headers for websocket support.

```bash
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
```

--------------------------------

### Nginx reverse proxy for Stash

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/reverse-proxy.md

Basic Nginx reverse proxy configuration for Stash. Sets required headers for WebSocket support and a 60-second read timeout.

```bash
location / {
    proxy_pass http://127.0.0.1:9999;
    
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_read_timeout 60000s;
}
```

--------------------------------

### Authenticate with API key using curl

Source: https://github.com/stashapp/stash-docs/blob/main/docs/api.md

Sends a GraphQL query to the Stash API using an API key for authentication. Replace <your_api_key> with the API key from Settings > Security > Authentication and <graphql_query> with the raw query.

```shell
curl -X POST -H "ApiKey: <your_api_key>" -H "Content-Type: application/json" --data '{ "query": "<graphql_query>" }' localhost:9999/graphql
```

--------------------------------

### Caddy v2 reverse proxy for Stash

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/reverse-proxy.md

Caddy v2 reverse proxy configuration for Stash. Sets the Host, X-Real-IP, and X-Forwarded-Port headers. The `external_host` configuration option should be set to `http://stash.home`.

```bash
stash.example.com {
    reverse_proxy 127.0.0.1:9999 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-Port {server_port}
    }
}
```

--------------------------------

### Legacy cookie authentication with curl

Source: https://github.com/stashapp/stash-docs/blob/main/docs/api.md

Legacy cookie authentication for Stash API. First command logs in and saves cookies to cookie.txt; second command uses those cookies to send a GraphQL query. Obsolete since v0.7; use API key instead.

```shell
curl --verbose --cookie-jar cookie.txt --data 'username=stash&password=**' localhost:9999/login
curl --cookie cookie.txt -H "Content-Type: application/json" --data '{ "query": "<graphql_query>" }' localhost:9999/graphql
```

--------------------------------

### Nginx reverse proxy with /stash prefix

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/reverse-proxy.md

Nginx configuration to serve Stash under the `/stash` prefix. The trailing slash in `proxy_pass` removes the prefix from requested URLs, and `X-Forwarded-Prefix` is set to `/stash`.

```bash
location /stash/ {
    # Notice the trailing slash - this causes nginx to remove the /stash prefix from requested URLs
    proxy_pass http://192.168.0.1:9999/;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /stash;
    proxy_read_timeout 60000s;
}
```

--------------------------------

### POST /graphql

Source: https://github.com/stashapp/stash-docs/blob/main/docs/api.md

The GraphQL endpoint for the Stash API. All GraphQL queries and mutations are sent to this endpoint. Authentication is required via an API key header.

```APIDOC
## [POST] /graphql

### Description
This is the GraphQL endpoint for the Stash API. All GraphQL queries and mutations are sent to this endpoint.

### Method
POST

### Endpoint
`<server>:<port>/graphql` (default: `localhost:9999/graphql`)

### Authentication
Include the API key generated in Stash in the header of every request. The header name is `ApiKey`.

### Request Headers
- **ApiKey** (string) - Required - The API key for authentication.
- **Content-Type** (string) - Required - Must be set to `application/json`.

### Request Body
- **query** (string) - Required - The GraphQL query string.

### Request Example
```shell
curl -X POST -H "ApiKey: <your_api_key>" -H "Content-Type: application/json" --data '{ "query": "<graphql_query>" }' localhost:9999/graphql
```

### Response
Returns the result of the GraphQL query or mutation. The response format follows the GraphQL specification.

### Error Handling
If authentication fails, an error will be returned. Ensure the `ApiKey` header is correctly set.
```

--------------------------------

### Change Stash user and group

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Changes the user and group that Stash runs as. The config_dir and the stash-linux binary must be owned by the user that Stash runs as.

```shell
sysrc "stash_user=usernamegoeshere"
sysrc "stash_group=groupnamegoeshere"
```

--------------------------------

### Remux video file with ffmpeg

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/troubleshooting-video-playback.md

Remux the video file into a new container without re-encoding, copying video and audio streams. This is a good test to see if remuxing helps with playback issues.

```shell
ffmpeg -i big_buck_bunny.mkv -c:v copy -c:a copy remuxed_file.mkv
```

--------------------------------

### Change Stash config directory

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Changes the location where Stash stores configuration files and database. The path must end with config.yml even if it does not exist yet; Stash will create it. Ownership and permissions of the chosen location must be fixed.

```shell
sysrc "stash_config_dir=path/to/location/config.yml"
```

--------------------------------

### Change stash-linux binary location

Source: https://github.com/stashapp/stash-docs/blob/main/docs/installation/truenas.md

Changes the location of the stash-linux binary used by the rc.d script.

```shell
sysrc "stash_exec_bin=/path/to/stash-linux"
```

--------------------------------

### Delete all tags from Stash database

Source: https://github.com/stashapp/stash-docs/blob/main/docs/guides/manually-editing-the-stash-sqlite3-database.md

SQL commands to delete all tags from the Stash database. Note that this will not work if you have scene marker tags.

```sql
sqlite> DELETE FROM scenes_tags;
sqlite> DELETE FROM tags;
```
Tokens:
Raw