Installation¶

Peek Stash Browser can be deployed in several ways depending on your needs and environment.

Requirements¶

• Stash server with GraphQL API enabled and an API key configured (Settings → Security)
• Docker (or Docker on unRAID)
• Network access between Peek and Stash

Installation Methods¶

Option 1: unRAID¶

Template Installation¶

Step 1: Download the template file

Get the template from GitHub:

https://raw.githubusercontent.com/carrotwaxr/peek-stash-browser/main/unraid-template.xml

Step 2: Install the template

Step 3: Configure the container

1. Go to Docker tab → Add Container
2. Select "Peek" from User Templates dropdown
3. Configure required settings:
4. JWT Secret: Generate with openssl rand -hex 32 in unRAID terminal
5. App Data Directory: Path for Peek data (e.g., /mnt/user/appdata/peek-stash-browser)
6. Click Apply
7. Access at http://your-unraid-ip:6969
8. Complete the Setup Wizard to connect to your Stash server

Option 2: Docker (Single Container)¶

# Pull the latest image
docker pull carrotwaxr/peek-stash-browser:latest

# Generate JWT secret
export JWT_SECRET=$(openssl rand -base64 32)

# Run Peek
docker run -d \
  --name peek-stash-browser \
  -p 6969:80 \
  -v peek-data:/app/data \
  -e JWT_SECRET="${JWT_SECRET}" \
  carrotwaxr/peek-stash-browser:latest

Volume Mounts:

• peek-data - Database and app data (Docker named volume)

Required Environment Variables:

• JWT_SECRET - Secret for JWT authentication (recommended to set manually)

Note: Stash URL and API key are configured via the Setup Wizard on first access - no environment variables needed!

See Configuration Guide for all environment variables.

Windows Examples¶

# Pull the latest image from Docker Hub
docker pull carrotwaxr/peek-stash-browser:latest

# Generate JWT secret (one-time)
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$bytes = New-Object byte[] 32
$rng.GetBytes($bytes)
$jwt = [Convert]::ToBase64String($bytes)

# Run Peek
docker run -d `
    --name peek-stash-browser `
    -p 6969:80 `
    -v peek-data:/app/data `
    -e JWT_SECRET=$jwt `
    carrotwaxr/peek-stash-browser:latest

Managing the container:

# View logs
docker logs peek-stash-browser

# Stop container
docker stop peek-stash-browser

# Start container
docker start peek-stash-browser

# Restart container
docker restart peek-stash-browser

# Update to new version
docker stop peek-stash-browser
docker rm peek-stash-browser
docker pull carrotwaxr/peek-stash-browser:latest
# Then re-run the docker run command above

Linux/macOS Examples¶

# Pull the latest image from Docker Hub
docker pull carrotwaxr/peek-stash-browser:latest

# Generate a secure random JWT secret
export JWT_SECRET=$(openssl rand -base64 32)

# Run Peek
docker run -d \
    --name peek-stash-browser \
    -p 6969:80 \
    -v peek-data:/app/data \
    -e JWT_SECRET="${JWT_SECRET}" \
    carrotwaxr/peek-stash-browser:latest

Managing the container:

# View logs
docker logs peek-stash-browser

# Follow logs in real-time
docker logs -f peek-stash-browser

# Stop container
docker stop peek-stash-browser

# Start container
docker start peek-stash-browser

# Restart container
docker restart peek-stash-browser

# Update to new version
docker stop peek-stash-browser
docker rm peek-stash-browser
docker pull carrotwaxr/peek-stash-browser:latest
# Then re-run the docker run command above

First Access & Setup Wizard¶

After installation, access Peek in your browser for the first-time setup:

1. Navigate to http://localhost:6969 (or your server IP)
2. Complete the 4-step setup wizard:
3. Welcome: Introduction to Peek
4. Create Admin: Set your admin username and password
5. Connect to Stash: Enter your Stash URL and API key
6. Complete: Setup finished!
7. Login with your newly created admin credentials

Updating Peek¶

Check for Updates¶

Peek includes a built-in update checker:

1. Navigate to Settings → Server Settings
2. Scroll to the Version Information section
3. Click Check for Updates

The system will query GitHub for new releases and notify you if an update is available.

Update Procedure¶

To update your Docker container to the latest version:

# Stop and remove current container
docker stop peek-stash-browser
docker rm peek-stash-browser

# Pull latest image
docker pull carrotwaxr/peek-stash-browser:latest

# Restart with same docker run command you used for installation
docker run -d \
  --name peek-stash-browser \
  -p 6969:80 \
  -v peek-data:/app/data \
  -e JWT_SECRET="${JWT_SECRET}" \
  carrotwaxr/peek-stash-browser:latest

# Stop and remove current container
docker stop peek-stash-browser
docker rm peek-stash-browser

# Pull latest image
docker pull carrotwaxr/peek-stash-browser:latest

# Restart with same docker run command you used for installation
docker run -d `
  --name peek-stash-browser `
  -p 6969:80 `
  -v peek-data:/app/data `
  -e JWT_SECRET=$jwt `
  carrotwaxr/peek-stash-browser:latest

Version Pinning¶

To use a specific version instead of :latest:

# Pull and use specific version
docker pull carrotwaxr/peek-stash-browser:1.0.0
docker run ... carrotwaxr/peek-stash-browser:1.0.0

Available versions: GitHub Releases

Port Configuration¶

Peek uses a single port for production deployments:

-p 6970:80   # Use 6970 instead of 6969

Hardware Recommendations¶

Peek is lightweight - it proxies streams through Stash rather than transcoding locally.

Next Steps¶

• Configure environment variables
• Quick Start Guide
• Troubleshooting