Stash

https://docs.stashapp.cc/
Admin
Stash is a self-hosted web application written in Go for serving and organizing a porn collection,...
Tokens:42,311
Snippets:698
Trust Score:8.2
Update:2 months ago
Show doc for...
Tokens:
Raw
### Enable and start Stash service

Source: https://docs.stashapp.cc/installation/truenas

Commands to enable the service at boot and start it immediately.

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

```shell
service stash start
```

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

### Enable and Start Stash Service

Source: https://docs.stashapp.cc/installation/synology

Register and launch the Stash service using systemctl.

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

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

### Install ffmpeg

Source: https://docs.stashapp.cc/installation/truenas

Install the required ffmpeg package within the jail.

```shell
pkg install ffmpeg
```

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

### Run the Stash command-line application

Source: https://docs.stashapp.cc/installation/macos

Execute the binary directly from the terminal to start the server.

```bash
./stash-macos
```

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

### Install Stash via Scoop

Source: https://docs.stashapp.cc/installation/windows

Commands to add the extras bucket and install the Stash package using the Scoop command-line manager.

```bash
scoop bucket add extras
```

```bash
scoop install stash
```

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

### Prepare Python Environment

Source: https://docs.stashapp.cc/installation/synology

Set up a virtual environment and install necessary Python dependencies for scrapers and plugins.

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

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

### Configure plugin assets

Source: https://docs.stashapp.cc/in-app-manual/plugins

Example mapping of URL prefixes to filesystem paths for plugin assets.

```yaml
assets:
  foo: bar
  /: .
```

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

### Example Scene Update Hook Arguments

Source: https://docs.stashapp.cc/in-app-manual/plugins

An example of the args object structure for a Scene update operation hook.

```json
{
    "hookContext": {
        "type":"Scene.Update.Post",
        "id":45,
        "input":{
            "clientMutationId":null,
            "id":"45",
            "title":null,
            "details":null,
            "url":null,
            "date":null,
            "rating":null,
            "organized":null,
            "studio_id":null,
            "gallery_ids":null,
            "performer_ids":null,
            "groups":null,
            "tag_ids":["21"],
            "cover_image":null,
            "stash_ids":null
        },
        "inputFields":[
            "tag_ids",
            "id"
        ]
    }
}
```

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

### Start Stash with Docker Compose

Source: https://docs.stashapp.cc/installation/docker

Command to initialize and start the Stash container in detached mode.

```bash
docker compose up -d
```

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

### Timestamp Format Example

Source: https://docs.stashapp.cc/in-app-manual/tasks/jsonspec

The standard format for created_at and updated_at fields.

```text
YYYY-MM-DDThh:mm:ssTZD
```

```json
"created_at": "2019-05-03T21:36:58+01:00"
```

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

### Example .stashignore file

Source: https://docs.stashapp.cc/in-app-manual/tasks

A sample configuration file using gitignore-style syntax to exclude specific files and directories from the scanning process.

```text
# Ignore temporary files
*.tmp
*.log

# Ignore specific directories
temp/
.thumbnails/

# But keep this specific file
!important.tmp
```

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

### Install Scraper Dependencies

Source: https://docs.stashapp.cc/installation/synology

Use pipreqs to scan and install dependencies required by installed scrapers and plugins.

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

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

### Configure scrapeXPath Action

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Example configuration for using an XPath scraper to parse a specific URL.

```yaml
sceneByURL:
- action: scrapeXPath
  url: 
    - pornhub.com/view_video.php
  scraper: sceneScraper
```

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

### Extract a video sample with ffmpeg

Source: https://docs.stashapp.cc/guides/troubleshooting-video-playback?q=

Creates a short clip from a specific start time to share for analysis.

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

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

### Regex Replacement

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Example of using the replace post-process to modify string content via regex.

```yaml
CareerLength: 
  selector: $infoPiece[text() = 'Career Start and End:']/../span[@class="smallInfo"]
    postProcess:
      - replace:
          - regex: \s+to\s+
            with: "-"
```

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

### Configure Cookies for Direct and CDP Scrapers

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment

Examples showing cookie configuration for native xpath scrapers versus CDP-based scrapers.

```yaml
driver:
  cookies:
    - CookieURL: "https://www.example.com"
      Cookies:
        - Name: "_warning"
          Domain: ".example.com"
          Value: "true"
          Path: "/"
        - Name: "_test2"
          Value: "123412"
          Domain: ".example.com"
          Path: "/"
    - CookieURL: "https://api.somewhere.com"
      Cookies:
        - Name: "_warn"
          Value: "123"
          Domain: ".somewhere.com"
```

```yaml
driver:
  useCDP: true
  cookies:
    - Cookies:
        - Name: "_warning"
          Domain: ".example.com"
          Value: "true"
          Path: "/"
        - Name: "_test2"
          Value: "123412"
          Domain: ".example.com"
          Path: "/"
    - Cookies:
        - Name: "_warn"
          Value: "123"
          Domain: ".somewhere.com"
```

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

### CDP Click Interaction Demo

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Example of using the driver clicks configuration to toggle elements on a page before scraping.

```yaml
name: clickDemo # demo only for a single URL
sceneByURL:
  - action: scrapeXPath
    url:
      - https://getbootstrap.com/docs/4.3/components/collapse/
    scraper: sceneScraper

xPathScrapers:
  sceneScraper:
    scene:
      Title: //head/title
      Details: # shows the id/s of the visible div/s for the Multiple targets example of the page
        selector: //div[@class="bd-example"]//div[@class="multi-collapse collapse show"]/@id
        concat: "\n\n"

driver:
  useCDP: true
  sleep: 1
  clicks: # demo usage toggle on off multiple times
    - xpath: //a[@href="#multiCollapseExample1"] # toggle on first element
    - xpath: //button[@data-target="#multiCollapseExample2"] # toggle on second element
      sleep: 4
    - xpath: //a[@href="#multiCollapseExample1"] # toggle off fist element
      sleep: 1
    - xpath: //button[@data-target="#multiCollapseExample2"] # toggle off second element
    - xpath: //button[@data-target="#multiCollapseExample2"] # toggle on second element
```

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

### Map, feetToCm, and lbToKg Post-Processing

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Example of using map, feetToCm, and lbToKg to transform scraped performer data.

```yaml
performer:
  Gender:
    selector: //div[@class="example element"]
    postProcess:
      - map:
          F: Female
          M: Male
  Height:
    selector: //span[@id="height"]
    postProcess:
      - feetToCm: true
  Weight:
    selector: //span[@id="weight"]
    postProcess:
      - lbToKg: true
```

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

### Patching InteractiveClient.connect

Source: https://docs.stashapp.cc/in-app-manual/plugins/uipluginapi

Example of overriding the connect method of the interactive client to add custom logging.

```javascript
InteractiveUtils.interactiveClientProvider = (
  opts
) => {
  if (!opts.defaultClientProvider) {
    throw new Error('invalid setup');
  }

  const client = opts.defaultClientProvider(opts);
  const connect = client.connect;
  client.connect = async () => {
      console.log('patching connect method');
      return connect.call(client);
    };

  return client;
};
```

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

### Initialize rc.d script

Source: https://docs.stashapp.cc/installation/truenas

Prepare the directory and file for the startup script.

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

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

### Configure NAS Startup Profile

Source: https://docs.stashapp.cc/installation/synology

Update the user profile to include the necessary path and activate the Python virtual environment on login.

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

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

### Parse Unix Timestamp

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Example of using parseDate with the unix format.

```yaml
Date:
  selector: //div[@class="value epoch"]/text()
  postProcess:
    - parseDate: unix
```

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

### Download and prepare stash-linux binary

Source: https://docs.stashapp.cc/installation/truenas

Fetch the binary from GitHub and set appropriate permissions.

```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
```

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

### Using {inputHostname} Placeholder

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Uses the inputHostname placeholder to set a fixed studio value and a dynamic selector.

```yaml
scene:
  Studio:
    fixed: "{inputHostname}"
  Details:
    selector: //div[@data-domain="{inputHostname}"]//p[@class="description"]
```

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

### Create configuration directory

Source: https://docs.stashapp.cc/installation/truenas

Create the directory for Stash configuration and set ownership.

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

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

### Split Attribute Values

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Example of using the split attribute to divide a string into multiple elements.

```yaml
Tags:
  Name:
    selector: //span[@class="list_attributes"]
    split: ","
```

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

### Subtract Days from Date

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Example of using replace and subtractDays to calculate a date from a relative string.

```yaml
Date:
  selector: //strong[contains(text(),"Added:")]/following-sibling::text()
  postProcess:
    - replace:
        - regex: (\d+)\sdays\sago.+
          with: $1
    - subtractDays: true
```

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

### Configure plugin execution with arguments

Source: https://docs.stashapp.cc/in-app-manual/plugins/externalplugins

Defines the binary and arguments for a plugin, where the first element is the executable.

```yaml
exec:
  - my_plugin
  - foo
  - bar
```

```yaml
exec:
  - python
  - {pluginDir}/foo.py
```

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

### Configure sceneByFragment with queryURLReplace

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Demonstrates using placeholders like {filename} in a queryURL and applying regex replacements to the value before execution.

```yaml
sceneByFragment:
  action: scrapeJson
  scraper: sceneQueryScraper
  queryURL: https://metadataapi.net/api/scenes?parse={filename}&limit=1
  queryURLReplace:
    filename:
      - regex: <some regex>
        with: <replacement>
```

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

### Return plugin output using Javascript

Source: https://docs.stashapp.cc/in-app-manual/plugins/embeddedplugins

Demonstrates different patterns for returning an output object from a Javascript plugin task.

```javascript
(function() {
    return {
        Output: "ok"
    };
})();
```

```javascript
function main() {
    return {
        Output: "ok"
    };
}

main();
```

```javascript
var output = {
    Output: "ok"
};

output;
```

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

### Return plugin output using a main function

Source: https://docs.stashapp.cc/in-app-manual/plugins/embeddedplugins?q=

Defines a main function and executes it to return the plugin output.

```javascript
function main() {
    return {
        Output: "ok"
    };
}

main();
```

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

### Create Systemd Service File

Source: https://docs.stashapp.cc/installation/synology

Define a systemd service unit to manage the Stash process at startup.

```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
```

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

### Invalid Recursive Common Fragment

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Example of an invalid configuration where a common fragment references another common fragment.

```yaml
common:
  $info: //div[@class="info"]
  # Referencing $info in $models will cause an error
  $models: $info/a[@class="model"]
scene:
  Title: $info/h1
  Performers:
    Name: $models
    URL: $models/@href
```

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

### Apache Module Prerequisites

Source: https://docs.stashapp.cc/guides/reverse-proxy?q=

Required Apache modules to enable proxying, headers, and SSL functionality.

```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
```

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

### Make the Stash binary executable

Source: https://docs.stashapp.cc/installation/macos

Grant execution permissions to the binary if it fails to run after download.

```bash
chmod u+x stash-macos
```

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

### Regex Exclusion Patterns

Source: https://docs.stashapp.cc/in-app-manual/configuration

Examples of regex patterns used to exclude files or directories from the Stash database. Note that backslashes must be double-escaped when editing the configuration file directly.

```regex
"sample\.mp4$"
```

```regex
"/\.[[:word:]]+/"
```

```regex
"c:\\stash\\videos\\exclude"
```

```regex
"^/stash/videos/exclude/"
```

```regex
"\\\\stash\\network\\share\\excl\\"
```

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

### Using {inputURL} Placeholder

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Uses the inputURL placeholder to set a fixed URL value and a selector for the title.

```yaml
scene:
  URL:
    fixed: "{inputURL}"
  Title:
    selector: //h1[@class="title"]
```

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

### Advanced Placeholder Usage in Selectors

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Demonstrates using both inputURL and inputHostname placeholders within selector strings.

```yaml
scene:
  Details:
    selector: //div[@data-url="{inputURL}"]//p[@class="description"]
  Site:
    selector: //div[@data-host="{inputHostname}"]//span[@class="site-name"]
```

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

### Opening the Stash database

Source: https://docs.stashapp.cc/guides/manually-editing-the-stash-sqlite3-database?q=

Navigate to the configuration directory and open the database file using the sqlite3 client.

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

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

### Configure sceneByURL with URL regex replacement

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Uses the {url} placeholder to transform a source URL into an API-compatible format via regex.

```yaml
sceneByURL:
  - action: scrapeJson
    url:
      - metartnetwork.com
    scraper: sceneScraper
    queryURL: "{url}"
    queryURLReplace:
      url:
        - regex: '^(?:.+\.)?([^.]+)\.com/.+movie/(\d+)/(\w+)/?$'
          with: https://www.$1.com/api/movie?name=$3&date=$2
```

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

### Configure performerByName with scrapeXPath

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Uses queryURL with a placeholder to search for performers and maps the result to a performer scraper.

```yaml
name: Boobpedia
performerByName:
  action: scrapeXPath
  queryURL: http://www.boobpedia.com/wiki/index.php?title=Special%3ASearch&search={}&fulltext=Search
  scraper: performerSearch
performerByURL:
  - action: scrapeXPath
    url: 
      - boobpedia.com/boobs/
    scraper: performerScraper
xPathScrapers:
  performerSearch:
    performer:
      Name: # name element
      URL: # URL element that matches the boobpedia.com/boobs/ URL above
  performerScraper:
    # ... performer scraper details ...
```

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

### Link FFmpeg and FFprobe

Source: https://docs.stashapp.cc/installation/synology

Create symbolic links for FFmpeg and FFprobe to ensure they are accessible in the system 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
```

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

### Stash rc.d script content

Source: https://docs.stashapp.cc/installation/truenas

The content for the /usr/local/etc/rc.d/stash startup script.

```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
```

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

### Configure plugin execution with a Python script

Source: https://docs.stashapp.cc/in-app-manual/plugins/externalplugins?q=

Uses the {pluginDir} placeholder to reference a script located in the same directory as the configuration file.

```yaml
exec:
  - python
  - {pluginDir}/foo.py
```

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

### Configure optional settings via sysrc

Source: https://docs.stashapp.cc/installation/truenas

Commands to customize Stash configuration paths, user, group, and binary location.

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

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

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

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

### Configure Nginx with URL Prefix

Source: https://docs.stashapp.cc/guides/reverse-proxy

Nginx configuration for serving Stash under a specific URL path prefix.

```nginx
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;
}
```

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

### Configure Custom Served Folders

Source: https://docs.stashapp.cc/in-app-manual/interface

Define custom folder mappings in config.yml to expose local directories to the UI via the /custom path.

```yaml
custom_served_folders:
  /: D:\stash\static
  /foo: D:\bar
```

```yaml
custom_served_folders:
  /: <stash folder>\custom
```

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

### Define a plugin configuration file

Source: https://docs.stashapp.cc/in-app-manual/plugins

The base YAML structure for defining plugin metadata, UI assets, and task execution settings.

```yaml
name: <plugin name> 
# optional list of dependencies to be included
# "#" is is part of the config - do not remove
# requires: <plugin ID>
description: <optional description of the plugin>
version: <optional version tag>
url: <optional url>

ui:
  # optional list of css files to include in the UI
  css:
    - <path to css file>

  # optional list of js files to include in the UI
  javascript:
    - <path to javascript file>

  # optional list of plugin IDs to load prior to this plugin
  requires:
    - <plugin ID>

  # optional list of assets 
  assets:
    urlPrefix: fsLocation
    ...

  # content-security policy overrides
  csp:
    script-src:
      - http://alloweddomain.com

    style-src:
      - http://alloweddomain.com

    connect-src:
      - http://alloweddomain.com

# map of setting names to be displayed in the plugins page in the UI
settings:
  # internal name
  foo:
  # name to display in the UI
  displayName: Foo
  # type of the attribute to show in the UI
  # can be BOOLEAN, NUMBER, or STRING
  type: BOOLEAN

# the following are used for plugin tasks only
exec:
  - ...
interface: [interface type]
errLog: [one of none trace, debug, info, warning, error]
tasks:
  - ...
```

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

### Configure Script Action

Source: https://docs.stashapp.cc/in-app-manual/scraping/scraperdevelopment?q=

Defines the script execution configuration using a list of arguments.

```yaml
action: script
script:
  - python
  - iafdScrape.py
  - query
```
Tokens:
Raw