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. App Data Directory: Path for Peek data (e.g., /mnt/user/appdata/peek-stash-browser)
5. Under "Show more settings" (advanced, all optional):
   • JWT Secret Key: leave empty and Peek generates one in /app/data/.jwt-secret on first start
   • PUID / PGID: the user and group that own the App Data Directory. They default to 99 and 100 (unRAID's nobody:users), which suits a folder under /mnt/user/appdata. See File ownership
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

# Run Peek
docker run -d \
  --name peek-stash-browser \
  -p 6969:80 \
  -v peek-data:/app/data \
  --restart unless-stopped \
  carrotwaxr/peek-stash-browser:latest

Volume Mounts:

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

Environment Variables: none are required.

• JWT_SECRET (optional) - Signs login sessions. When unset, Peek generates one on first start and keeps it in /app/data/.jwt-secret
• PUID / PGID (optional) - The user and group that own /app/data, default 99 and 100. See File ownership

services:
  peek:
    image: carrotwaxr/peek-stash-browser:latest
    ports:
      - "6969:80"
    volumes:
      - /home/you/peek:/app/data
    environment:
      - PUID=1000 # the output of id -u
      - PGID=1000 # the output of id -g
    restart: unless-stopped

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

# Run Peek
docker run -d `
    --name peek-stash-browser `
    -p 6969:80 `
    -v peek-data:/app/data `
    --restart unless-stopped `
    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

# Run Peek
docker run -d \
    --name peek-stash-browser \
    -p 6969:80 \
    -v peek-data:/app/data \
    --restart unless-stopped \
    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

File ownership (PUID/PGID)¶

Peek does not run as root. The container starts as root only long enough to set up its app user, then runs the server as PUID:PGID:

• PUID and PGID default to 99 and 100, unRAID's nobody:users. With a named volume, nothing else is needed.
• On every start, the entrypoint gives /app/data to PUID:PGID. It changes only files with a different owner, so later starts are quick, and it keeps file modes (0600 on .jwt-secret).
• If you set CONFIG_DIR to a directory outside /app/data, that directory is given to PUID:PGID too.
• nginx's master process stays root to listen on port 80; its workers run as PUID:PGID.
• If the data directory cannot change owner (NFS with root squash, SMB/CIFS, a read-only mount) and PUID:PGID cannot write to it, the container stops with [entrypoint] ERROR: /app/data is not writable by UID:GID. Set PUID/PGID to the owner that ls -ln shows for the directory.
• PUID=0 keeps the server running as root. Use it only where the data directory cannot change owner, such as rootless Docker or Podman. Peek logs a warning at every start.
• docker run --user (or user: in Compose) is refused: the container exits with this image manages its own user. Remove it and set PUID/PGID instead.

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 User: The username is admin; choose a 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 → Server Configuration
2. Scroll to the Version Information section
3. Peek checks for a newer release when you open it; click Check for Updates to check again

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 \
  --restart unless-stopped \
  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 `
  --restart unless-stopped `
  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:3.3.8
docker run ... carrotwaxr/peek-stash-browser:3.3.8

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