### Enable and Start Stash Systemd Service

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

Enables the Stash service to start automatically on system boot and then starts the service immediately. This ensures Stash runs in the background.

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

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

### Install Python Scraper and Plugin Dependencies

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

Installs dependencies for Stash scrapers and plugins. It uses pipreqs to generate a requirements.txt file based on the installed scrapers and plugins, then installs them using pip.

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

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

### Enable and Start Stash Service

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

Commands to enable the Stash service to start automatically at boot and to manually start the service. After starting, Stash is accessible via HTTP.

```shell
sysrc "stash_enable=YES"
service stash start
```

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

### Create Stash rc.d Startup Script

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

This script configures Stash to run as a daemon. It sets up necessary variables for the service name, user, group, configuration directory, and the executable binary. It also defines how to start and stop the service, including pre-start commands to ensure the PID file is correctly set up.

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

```

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

### Install Python Dependencies for Stash-Docs

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

Installs all necessary Python modules for local development of the Stash-Docs website using pip. This command ensures that the mkdocs-material theme and various plugins are correctly set up.

```bash
pip install mkdocs-material=="9.*" mkdocs-git-revision-date-localized-plugin mkdocs-git-committers-plugin-2 mkdocs-glightbox "mkdocs-material[imaging]" mkdocs-redirects
```

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

### Extract Video Sample with ffmpeg

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

Extract a specific duration sample from a video file, starting at a given timestamp. This is useful for providing samples 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
```

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

### Stash Configuration Options (YAML)

Source: https://context7.com/stashapp/stash-docs/llms.txt

Example of advanced configuration options for Stash using the config.yml file. Covers network settings, paths, upload limits, proxy configuration, and custom served folders.

```yaml
# config.yml - Advanced configuration options
host: 0.0.0.0                    # IP address Stash listens on (default: 0.0.0.0)
port: 9999                       # Port Stash serves on (default: 9999)
external_host: http://stash.example.com  # Public hostname for reverse proxy
plugins_path: /custom/plugins    # Override default plugins folder
scrapers_path: /custom/scrapers  # Override default scrapers folder
max_upload_size: 2048            # Maximum upload size in MB (default: 1024)
proxy: https://user:password@my.proxy:8080  # HTTP(S) proxy URL
no_proxy: localhost,127.0.0.1,192.168.0.0/16,10.0.0.0/8  # Proxy exclusions

# Custom served folders mapping
custom_served_folders:
  /custom-path: /path/on/filesystem
```

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

### Install ffmpeg on TrueNAS CORE Jail

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

Installs the ffmpeg package within an iocage jail on TrueNAS CORE. This is a prerequisite for Stash to process media files.

```shell
pkg install ffmpeg
```

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

### External Plugins API

Source: https://github.com/stashapp/stash-docs/blob/main/docs/in-app-manual/plugins/externalplugins.md

This section outlines the API endpoints related to managing external plugins. It covers listing available plugins, installing new ones, and managing their configurations.

```APIDOC
## External Plugins Management

### Description
This section details the API endpoints for managing external plugins within Stash. You can list available plugins, install new ones from a URL, and manage their configurations.

### Method
GET, POST

### Endpoint
/api/v1/plugins

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filters the list of plugins by name or keyword.

#### Request Body (for POST)
- **url** (string) - Required - The URL to the plugin archive for installation.

### Request Example (Install Plugin)
```json
{
  "url": "http://example.com/path/to/plugin.zip"
}
```

### Response
#### Success Response (200)
- **plugins** (array) - A list of available plugins, each with details like name, version, and status.
- **installed_plugins** (array) - A list of currently installed plugins.

#### Response Example (List Plugins)
```json
{
  "plugins": [
    {
      "name": "ExamplePlugin",
      "version": "1.0.0",
      "description": "A sample external plugin.",
      "installed": true
    }
  ],
  "installed_plugins": [
    {
      "name": "ExamplePlugin",
      "version": "1.0.0",
      "enabled": true
    }
  ]
}
```

#### Error Response (400)
- **error** (string) - Description of the error (e.g., "Invalid URL provided").

#### Error Response (500)
- **error** (string) - Description of the server error.
```

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

### Prepare Python Environment for Stash

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

Sets up a dedicated Python 3.11 environment for Stash scrapers and plugins. It ensures pip is updated, creates a virtual environment named 'stash-env', activates it, and installs pipreqs.

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

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

### GraphQL API Queries with cURL

Source: https://context7.com/stashapp/stash-docs/llms.txt

Demonstrates how to interact with the Stash GraphQL API using cURL. Includes examples for basic queries, filtering scenes, and authentication methods (API key and deprecated cookie authentication).

```bash
# Basic GraphQL query with API key authentication
curl -X POST \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query": "{ allScenes { id title } }"}' \
  http://localhost:9999/graphql

# Query scenes with filtering
curl -X POST \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "query FindScenes($filter: FindFilterType) { findScenes(filter: $filter) { count scenes { id title date studio { name } } } }",
    "variables": {
      "filter": {
        "per_page": 10,
        "page": 1
      }
    }
  }' \
  http://localhost:9999/graphql

# Legacy cookie authentication (deprecated since v0.7)
curl --verbose --cookie-jar cookie.txt \
  --data 'username=stash&password=yourpassword' \
  http://localhost:9999/login

curl --cookie cookie.txt \
  -H "Content-Type: application/json" \
  --data '{"query": "{ allPerformers { id name } }"}' \
  http://localhost:9999/graphql
```

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

### Docker Compose for Stash Deployment

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

This Docker Compose configuration defines a production-ready setup for the Stash application. It specifies the image to use, container name, restart policy, port mappings, logging options, environment variables for data paths, and volume mounts for configuration, data, metadata, cache, blobs, and generated content.

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

```

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

### Stash API: Legacy Cookie Authentication for GraphQL (curl)

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

This example shows the legacy method of authenticating with the Stash API using cookies, which is now obsolete. It involves a two-step process: first, logging in to obtain cookies, and then using those cookies to execute a GraphQL query. This method is not recommended for new implementations.

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

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

### Link ffprobe and ffmpeg Binaries

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

Creates symbolic links for ffprobe and ffmpeg to ensure they are accessible in the system's PATH. This is crucial for Stash to utilize these media processing tools.

```bash
sudo ln -s /var/packages/ffmpeg6/target/bin/ffprobe /usr/local/bin/ffprobe
sudo ln -s /var/packages/ffmpeg6/target/bin/ffmpeg /usr/local/bin/ffmpeg
```

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

### Stash Configuration via Environment Variables and Flags

Source: https://context7.com/stashapp/stash-docs/llms.txt

Shows alternative methods for configuring Stash using environment variables or command-line flags. These are useful for dynamic configuration or when overriding default settings.

```bash
# Environment variable configuration
STASH_HOST=0.0.0.0 STASH_PORT=9999 ./stash

# Command-line flag configuration
./stash --host 0.0.0.0 --port 9999
```

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

### Configure NAS Profile for Stash

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

Creates and modifies the .profile file in the user's home directory to include the Stash executable path and activate the Stash Python environment automatically on login.

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

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

### GraphQL API Endpoint

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

This section details how to access the Stash GraphQL API endpoint and provides an example using curl for making POST requests with API key authentication.

```APIDOC
## POST /graphql

### Description
This endpoint allows you to interact with the Stash GraphQL API to perform various operations by sending GraphQL queries or mutations.

### Method
POST

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

### Parameters
#### Headers
- **ApiKey** (string) - Required - Your Stash API key for authentication.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **query** (string) - Required - The GraphQL query or mutation to execute.

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

### Response
#### Success Response (200)
- **data** (object) - Contains the result of the GraphQL query or mutation.
- **errors** (array) - Contains any errors encountered during query execution.

#### Response Example
```json
{
  "data": {
    "users": [
      {
        "id": "1",
        "name": "John Doe"
      }
    ]
  }
}
```
```

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

### Download and Prepare stash-linux Binary on TrueNAS CORE

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

Downloads the stash-linux binary from GitHub, sets its ownership to the 'stash' user and group, and makes it executable. This prepares the Stash executable for use within the TrueNAS CORE jail.

```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 Information with ffprobe

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

Use the ffprobe command to gather detailed information about a video file's format and streams. This is helpful for bug reports and discussions.

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

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

### Download Stash Application for Different Architectures

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

Downloads the latest version of Stash for Linux, with specific files for different CPU architectures (x86_64, arm32v6, arm32v7, arm64v8). It also downloads the checksum file for validation.

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

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

### Nginx Reverse Proxy with External Host Configuration

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

This Nginx configuration is used when the `external_host` setting is configured in Stash's `config.yml`. It directs traffic to Stash's IP and port while ensuring the correct `Host` header is passed. This is useful for custom domain setups.

```nginx
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 Reverse Proxy with URL Prefix

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

This Nginx configuration enables Stash to run under a URL prefix (e.g., `/stash`). It requires the `X-Forwarded-Prefix` header to be set and ensures the prefix is removed from requested URLs by using a trailing slash in `proxy_pass`. This setup is crucial for accessing Stash at a subpath.

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

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

### Create Stash Systemd Service File

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

Defines a systemd service file named 'stash.service' to manage the Stash application. It specifies the description, dependencies, working directory, user, execution command, and restart behavior.

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

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

### Stash Database Backup and Restore Procedures

Source: https://context7.com/stashapp/stash-docs/llms.txt

Instructions for managing SQLite database backups for Stash, emphasizing the use of WAL mode and the correct backup/restore process via the Stash UI or manual steps.

```bash
# Database files location (do NOT copy directly while Stash is running)
# stash-go.sqlite      - Main database file
# stash-go.sqlite-shm  - Shared memory file (WAL mode)
# stash-go.sqlite-wal  - Write-ahead log file

# Backup via Settings > Tasks > Backup or Download Backup
# Configure backup directory: Settings > System > Backup directory path

# Restore procedure:
# 1. Check database path: Settings > System > Database path
# 2. Check blob storage: Settings > System > Binary data storage type
# 3. If Filesystem blobs, restore blobs to: Binary data path
# 4. Stop Stash
# 5. Navigate to database directory
# 6. Remove: stash-go.sqlite, stash-go.sqlite-shm, stash-go.sqlite-wal, stash-go.sqlite.journal
# 7. Copy backup file as: stash-go.sqlite
# 8. Start Stash
```