# Introduction

Welcome to Petio's documentation! We aim to provide the most of up to date information about Petio's ongoing development so this wiki is always *under construction*.

 Feel free to contribute through GitHub or you can ask in [Discord](https://discord.gg/bseGmrUd3N) for something to be added, updated or corrected. We don't know everything but we sure appreciate people who know more than we do :grin:


# FAQ

## Roadmap

A public roadmap is planned and will be made soon!

## Plex oAuth

Petio supports Plex oAuth

## MongoDB

Petio doesn't use relational data. MongoDB in this instance is way faster for us to parse straight into the API worker.

## Single Season TV Show

At this time, only whole shows can be requested. However, TV Show request granularity is a planned enhancement

## Plex Library Scan

A partial scan is ran every 30 mins and a full scan is ran everyday at midnight.

## Unable to log in to the admin portal

If you aren't using Plex oAuth to sign in to Petio - when you first set up Petio, you were prompted to set up a custom password. Make sure you are using the correct password and not your Plex password.

## Localization

Translations will be a part of the next development phase using i18n strings.

## Request with a yellow warning

A TV request without a TVDB ID can't be passed to Sonarr, this is usually because TMDB doesn't have a TVDB ID for this show yet. Petio will check for the TVDB ID as part of a cron and once one is found it will be processed. You can also manualy add one to TMDB.

## Why are all my requests pending?

Are your requests being approved? Take a look at the user profiles. Still having issues? Read over our [user profiles](/configuration/user-profiles) section.

## Notifications/Webhooks

The current notification system will undergo an overhaul.

## Lidarr Support

Lidarr support is planned

## Backups

Backup options are planned including database backup

## Does Petio automatically update?

Currently only docker based installs can "auto-update" by pulling a new image. If you are running Petio using binaries you must download the latest release.


# Docker

If you notice any mistakes that need to be corrected, please reach out on Discord!

We will go over how to install Petio using [Docker](https://docs.docker.com/engine/) or [Docker Compose](https://docs.docker.com/compose/). We assume you have installed Docker and/or Docker Compose.

{% hint style="danger" %}
This guide will not walk you through how to install or configure any of these two services.
{% endhint %}

## Docker CLI

```
docker run --rm \
    --name petio \
    -p 7777:7777 \
    -e TZ="Etc/UTC" \
    --user 1000:1000 \
    -v /<host_folder_config>:/app/api/config \
    ghcr.io/petio-team/petio
```

```
docker run --rm \
    --name mongo \
    -e TZ="Etc/UTC" \
    --user 1000:1000 \
    -v /<host_folder_db>:/data/db \
    mongo:4.4
```

## Docker Compose

There are two ways you can install Petio using Docker Compose. You can either download the `docker-compose.yml` from the repo and place it in a folder where you will run `docker-compose` from or you can add it to an existing `docker-compose.yml`.

To download the Docker Compose file you run the following command:

```bash
curl -OL https://github.com/petio-team/petio/raw/master/docker-compose.yml -o /path/to/location
```

Below you can find an example for the `docker-compose.yml`. In this example, `petio` and `mongo` are on a custom docker network called `petio-network`

```yaml
version: '3'

networks:
    petio-network:
        driver: bridge

services:
    petio:
        image: ghcr.io/petio-team/petio:latest
        container_name: petio
        hostname: petio
        ports:
            - '7777:7777'
        networks:
            - petio-network
        user: '1000:1000'
        depends_on:
            - mongo
        environment:
            - TZ=Etc/UTC
        volumes:
            - ./config:/app/api/config
            - ./logs:/app/logs

    mongo:
        image: mongo:4.4
        container_name: mongo
        hostname: mongo
        networks:
            - petio-network
        user: '1000:1000'
        volumes:
            - ./db:/data/db
```

Once you configure the services, you need to spin up the container using `docker-compose up -d`.

Once the container is spun up, you can navigate to `http://<hostname>:7777` to start [configuring Petio](/configuration/first-time-setup).


# Linux

We provide install guides for some of the most popular Linux distros.

* [Debian/Ubuntu](/install-guides/linux/debian-ubuntu)
* [Red Hat/Cent OS](/install-guides/linux/red-hat-cent-os)

{% hint style="info" %}
If you wish to see an install guide specific to your distro feel free to contribute :sweat\_smile:&#x20;
{% endhint %}


# Debian 10/Ubuntu 20.04

If you notice any mistakes that need to be corrected, please reach out on Discord!

## MongoDB

Petio supports two ways of connecting to a Mongo Database instance, locally or remote. We recommend the locally hosted MongoDB option.

### **MongoDB Locally**

{% hint style="danger" %}
Make sure to add the correct repository to `apt` depending on whether you're using Debian or Ubuntu.
{% endhint %}

* Import the public key used by the package management system:

```bash
wget -qO - https://www.mongodb.org/static/pgp/server-4.4.asc | sudo apt-key add -
```

* Create the /etc/apt/sources.list.d/mongodb-org-4.4.list file:

{% tabs %}
{% tab title="Debian 10" %}

```bash
echo "deb http://repo.mongodb.org/apt/debian buster/mongodb-org/4.4 main" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list
```

{% endtab %}

{% tab title="Ubuntu 20.04" %}

```bash
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/4.4 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-4.4.list
```

{% endtab %}
{% endtabs %}

* Reload local package database:

```bash
sudo apt-get update
```

* Install the MongoDB packages:

```bash
sudo apt-get install -y mongodb-org
```

* Start MongoDB:

```bash
sudo systemctl start mongod
```

* Verify that MongoDB has started successfully:

```bash
sudo systemctl status mongod
```

* To make sure MongoDB starts after restart use:

```bash
sudo systemctl enable mongod
```

### MongoDB Locally - On A Different Host

By default, MongoDB doesn’t allow remote connections.

* Locate your `mongod.conf` and edit it with your favorite editor. Include any local IP addresses you want to allow to connect to your MongoDB instance.

```bash
vim /etc/mongod.conf
# /etc/mongod.conf
# Listen to local and LAN interfaces.
bind_ip = 127.0.0.1,192.168.161.100
```

* Restart the `mongod` service after making these changes

```bash
sudo systemctl restart mongod
```

If there is a firewall, you might need to use `iptables` to allow access to MongoDB. Example below:

* Any connections can connect to MongoDB on port 27017

```bash
iptables -A INPUT -p tcp --dport 27017 -j ACCEPT
```

* Only certain IPs can connect to MongoDB on port 27017

```bash
iptables -A INPUT -s <ip-address> -p tcp --destination-port 27017 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -A OUTPUT -d <ip-address> -p tcp --source-port 27017 -m state --state ESTABLISHED -j ACCEPT
```

### MongoDB Remotely

* Register for Atlas [here](https://www.mongodb.com/cloud/atlas/register).
* Create a free cluster.

![](/files/-MWpwKzvMm2w27RFKx9r)

* Change the provider or region if you need to. It may take some time to create the cluster.

![](/files/-MWpwKzuKe3yy1gb7f_A)

* After the cluster is made, click on connect and select MongoDB Compass and follow the instructions on screen.

![](/files/-MWpwKztq-smEhPkWGz9)

* Move on to the next section to start [installing Petio](/install-guides/linux/debian-ubuntu#installing-petio).

## Installing Petio

* Create a user for Petio:

```bash
sudo useradd -M --shell=/bin/false petio
```

* Make a directory for Petio:

```bash
sudo mkdir /opt/Petio
```

* Download the latest version of Petio:

```bash
sudo wget https://petio.tv/releases/latest -O petio-latest.zip
```

* Extract Petio to the directory we just made:

```bash
sudo unzip petio-latest.zip -d /opt/Petio
```

* Change ownership of the directory for Petio:

```bash
sudo chown -R petio:petio /opt/Petio
```

* Create the petio service with systemd:

{% code title="/etc/systemd/system/petio.service" %}

```bash
[Unit]
Description=Petio a content request system
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=1
ExecStart=/opt/Petio/bin/petio-linux
User=petio

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

{% endcode %}

* Reload systemd:

```bash
sudo systemctl daemon-reload
```

* Start Petio:

```bash
sudo systemctl start petio
```

Once you've completed theses steps, you can navigate to `http://<hostname>:7777` to start [configuring Petio](/configuration/first-time-setup).


# Red Hat/Cent OS

If you notice any mistakes that need to be corrected, please reach out on Discord!

## MongoDB

Petio supports two ways of connecting to a Mongo Database instance, locally or remote. We recommend the locally hosted MongoDB option.

### **MongoDB Locally**

* Configure the package management system (yum)
* Create a /etc/yum.repos.d/mongodb-org-4.4.repo file so that you can install MongoDB directly using yum:

```bash
sudo nano /etc/yum.repos.d/mongodb-org-4.4.repo
```

* Paste in the nano / terminal window:

```bash
[mongodb-org-4.4]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/4.4/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://www.mongodb.org/static/pgp/server-4.4.asc
```

* Press: "CTRL + O" to save and "CTRL+X" to exit.
* To install the latest stable version of MongoDB, issue the following command:

```bash
sudo yum install -y mongodb-org
```

* Start MongoDB:

```bash
sudo systemctl start mongod
```

* Verify that MongoDB has started successfully:

```bash
sudo systemctl status mongod
```

* To make sure MongoDB starts after restart use:

```bash
sudo systemctl enable mongod
```

### MongoDB Locally - On A Different Host

By default, MongoDB doesn’t allow remote connections.

* Locate your `mongod.conf` and edit it with your favorite editor. Include any local IP addresses you want to allow to connect to your MongoDB instance.

```bash
vim /etc/mongod.conf
# /etc/mongod.conf
# Listen to local and LAN interfaces.
bind_ip = 127.0.0.1,192.168.161.100
```

* Restart the `mongod` service after making these changes

```bash
sudo systemctl restart mongod
```

If there is a firewall, you might need to use `iptables` to allow access to MongoDB. Example below:

* Any connections can connect to MongoDB on port 27017

```bash
iptables -A INPUT -p tcp --dport 27017 -j ACCEPT
```

* Only certain IPs can connect to MongoDB on port 27017

```bash
iptables -A INPUT -s <ip-address> -p tcp --destination-port 27017 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -A OUTPUT -d <ip-address> -p tcp --source-port 27017 -m state --state ESTABLISHED -j ACCEPT
```

### MongoDB Remotely

* Register for Atlas [here](https://www.mongodb.com/cloud/atlas/register).
* Create a free cluster.

![](/files/-MWpwKzvMm2w27RFKx9r)

* Change the provider or region if you need to. It may take some time to create the cluster.

![](/files/-MWpwKzuKe3yy1gb7f_A)

* After the cluster is made, click on connect and select MongoDB Compass and follow the instructions on screen.

![](/files/-MWpwKztq-smEhPkWGz9)

* Move on to the next section to start [installing Petio](/install-guides/linux/red-hat-cent-os#installing-petio).

## Installing Petio

* Create a user for Petio:

```bash
sudo useradd -M --shell=/bin/false petio
```

* Make a directory for Petio:

```bash
sudo mkdir /opt/Petio
```

* Download the latest version of Petio:

```bash
sudo wget https://petio.tv/releases/latest -O petio-latest.zip
```

* Extract Petio to the directory we just made:

```bash
sudo unzip petio-latest.zip -d /opt/Petio
```

* Change ownership of the directory for Petio:

```bash
sudo chown -R petio:petio /opt/Petio
```

* Create the petio service with systemd:

```bash
sudo vi /etc/systemd/system/petio.service

[Unit]
Description=Petio a content request system
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=on-failure
RestartSec=1
ExecStart=/opt/Petio/bin/petio-linux
User=petio

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

* Reload systemd:

```bash
sudo systemctl daemon-reload
```

* Start Petio:

```bash
sudo systemctl start petio
```

Once you've completed theses steps, you can navigate to `http://<hostname>:7777` to start [configuring Petio](/configuration/first-time-setup).


# Updating Petio

We believe these instructions should be pretty OS agnostic, but if you notice any mistakes that need to be corrected, please reach out on Discord!

* Stop the Petio service.

  ```bash
  sudo systemctl stop petio
  ```
* Download the latest version of Petio.

  ```bash
  sudo wget https://petio.tv/releases/latest -O petio-latest.zip
  ```
* Extract to petio folder.

  ```bash
  sudo unzip petio-latest.zip -d /opt/Petio
  ```
* Start Petio service.

  ```bash
  sudo systemctl start petio
  ```
* Remove the file you downloaded so you are ready for a new update later on.

  ```bash
  sudo rm petio-latest.zip
  ```


# FreeBSD

## MongoDB

placeholder

## Installing Petio

There is no package built for FreeBSD so the application will have to be built from source

#### Building from source

```
## Install dependencies
pkg install mongodb
pkg install npm
pkg install git (only if you want to use git to checkout the source)
npm install -g typescript

## Clone the repo and build the application
mkdir -p /usr/local/share/petio
cd /usr/local/share/petio
git clone -b dev https://github.com/petio-team/petio.git .
cd pkg/admin
npm install
npm run build
cd ../frontend
npm install
npm run build
cd ../api
npm install
npm run build
cd
mkdir -p /usr/local/petio
chown $petio_user:$petio_group /usr/local/petio
su -m $petio_user
setenv VIEWS_FOLDER /usr/local/share/petio/pkg/
setenv DATA_FOLDER /usr/local/petio

# Run the application
node /usr/local/share/petio/pkg/api/dist/main.js --host 0.0.0.0 --port 7777
```

#### Create a Petio service

rc.d script to run petio. It checks whether mongod is enabled and running, warns if not, and forcefully starts it if not running.

* Place this script in `/usr/local/etc/rc.d/petio`
* Give it execute permissions: `chmod +x /usr/local/etc/rc.d/petio`
* Configure it in `/etc/rc.conf`
  * sysrc petio\_enable="YES"
  * optionally set user: `sysrc petio_user="petio"`
  * optionally set group: `sysrc petio_group="petio"`
  * optionally set data directory: `sysrc petio_data_dir="/usr/local/petio"`

```
#!/bin/sh

# PROVIDE: petio
# REQUIRE: DAEMON mongod
# BEFORE: LOGIN
# KEYWORD: shutdown

. /etc/rc.subr

name=petio
rcvar=petio_enable

load_rc_config $name

: ${petio_enable:="NO"}
: ${petio_user:="petio"}
: ${petio_group:="petio"}
: ${petio_data_dir:="/usr/local/petio"}

export NODE_ENV=production
export APP_DIR=/usr/local/share/petio
export VIEWS_FOLDER=/usr/local/share/petio/pkg/
export DATA_FOLDER=${petio_data_dir}

pidfile="/var/run/${name}/${name}.pid"
start_precmd="petio_precmd"

procname="/usr/local/bin/node"
command="/usr/sbin/daemon"
command_args="-f -p ${pidfile} ${procname} --no-warnings /usr/local/share/petio/pkg/api/dist/main.js --host 0.0.0.0 --port 7777"

petio_precmd()
{
        if [ ! -d $(dirname ${pidfile}) ]; then
                install -d -o ${petio_user} -g ${petio_group} $(dirname ${pidfile})
        fi

        if [ ! -d ${petio_data_dir} ]; then
                install -d -o ${petio_user} -g ${petio_group} ${petio_data_dir}
        fi

        # make sure mongod is running
        if ! checkyesno mongod_enable && \
                ! /usr/local/etc/rc.d/mongod forcestatus 1>/dev/null 2>&1; then
                        echo "Make sure to enable and start mongod"
                        /usr/local/etc/rc.d/mongod forcestart || return 1
        fi
        return 0
}

run_rc_command "$1"
```

Once you've completed these steps, you can navigate to `http://<hostname>:7777` to start [configuring Petio](/configuration/first-time-setup).&#x20;


# MacOS

If you notice any mistakes that need to be corrected, please reach out on Discord!

## MongoDB

Petio supports two ways of connecting to a Mongo Database instance, locally or remote. We recommend the locally hosted MongoDB option.

{% hint style="warning" %}
Macs with the new M1 chip (arm64 arch) do not yet support Mongo locally installed. Please use either Remote MongoDB Hosting or any of the [Docker ](/install-guides/docker)options.
{% endhint %}

### MongoDB Locally

{% hint style="info" %}
We assume you've installed [homebrew](https://brew.sh/#install) in order to follow this guide.
{% endhint %}

* Add the Official MongoDB Repo to homebrew:

```bash
brew tap mongodb/brew
```

* Install MongoDB:

```bash
brew install mongodb-community@4.4
```

* Start MongoDB as a service:

```bash
brew services start mongodb-community
```

### MongoDB Locally - On A Different Host

* Please review the [Linux guides](/install-guides/linux/debian-ubuntu#mongodb-locally-on-a-different-host) and make changes as necessary for your situation.

### MongoDB Remotely

* Register for Atlas [here](https://www.mongodb.com/cloud/atlas/register).
* Create a free cluster.

![](/files/-MWpwKzvMm2w27RFKx9r)

* Change the provider or region if you need to. It may take some time to create the cluster.

![](/files/-MWpwKzuKe3yy1gb7f_A)

* After the cluster is made, click on connect and select MongoDB Compass and follow the instructions on screen.

![](/files/-MWpwKztq-smEhPkWGz9)

* Move on to the next section to start [installing Petio](/install-guides/macos#petio-as-a-service).

## Petio as a Service

* First make a directory for Petio:

```bash
sudo mkdir /opt/Petio
```

* Download the latest version of Petio:

```bash
sudo curl -L https://petio.tv/releases/latest --output petio-latest.zip
```

* Extract Petio to the directory we just made:

```bash
sudo unzip petio-latest.zip -d /opt/Petio
```

* Change the permissions so that Petio can work as expected:

```bash
sudo chown -R ${USER}:staff /opt/Petio
```

* To have Petio running in the background without user input, we will use `launchctl.`
  * To more-or-less control `launchd`define a service for Petio like shown below and save it as `tv.petio.plist` in the `~/Library/LaunchAgents/` folder.

```markup
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>tv.petio</string>
        <key>ProgramArguments</key>
        <array>
            <string>/opt/Petio/bin/petio-macos</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
    </dict>
</plist>
```

* Load the service using:

```bash
launchctl load ~/Library/LaunchAgents/tv.petio.plist
```

* Start the service using:

```bash
launchctl start tv.petio
```

* Verify that Petio is indeed running:

```bash
launchctl list | grep tv.petio
```

* To stop Petio, run:

```bash
launchctl stop tv.petio
```

Once you've completed theses steps, you can navigate to `http://<hostname>:7777` to start [configuring Petio](/configuration/first-time-setup).

## Updating Petio

* Stop the Petio service with `launchctl`.
* Navigate to the directory you have Petio installed in, then, download the latest version from the [Downloads page](https://petio.tv/downloads/) with:

```bash
curl -L https://petio.tv/releases/latest --output petio-latest.zip
```

* Extract the contents of freshly downloaded archive while overwriting the current contents of the current directory with:

```bash
unzip -o petio-latest.zip -d ./
```

* Lastly, start the Petio service back up again with `launchctl`.


# UnRAID

If you notice any mistakes that need to be corrected, please reach out on Discord!

## MongoDB

### Community Applications

* Go to the Apps page within unRAID and search for `MongoDB`.&#x20;

{% hint style="danger" %}
You will have to set permissions on the appdata folder yourself. The MongoDB container does not have any logic in it to set the ownership.&#x20;
{% endhint %}

* There are two ways to do the permissions for this.
  * In Extra Parameters (you will have to enable the advanced view), set `--user 99:100` to run it as the user most containers created by the community run as. If you choose this - in your terminal run `chown nobody:users /mnt/user/appdata/mongodb/`
  * If you choose not to set the Extra Perameters - in your terminal run `chown 999:999 /mnt/user/appdata/mongodb/`

{% hint style="warning" %}
If you are using a different path, make sure you adjust the command as necesary.
{% endhint %}

* Make sure to restart the container after running the `chown` command

### MongoDB Locally - On A Different Host

* Please review the [Linux guides](/install-guides/linux/debian-ubuntu#mongodb-locally-on-a-different-host) and make changes as necessary for your situation.

## Petio

There are two ways to get Petio installed on unRAID. You can either import your own template or install it from the Community Applications plugin.

### Community Applications

* Go to the Apps page within unRAID and search for `Petio`. You can use either use ChargingCosmonaut's (Official) or Hotio's template.

![](/files/-MWprb4GIDHoVT-1umNe)

* Configure the container like all the others on unRAID.

![](/files/-MWpttfjhv3BhH3WRrgZ)

Once you've completed theses steps, you can navigate to `http://<hostname>:7777` to start [configuring Petio](/configuration/first-time-setup).

### Template

* Add the repo to `Template Repositories` under the Docker header:
  * <https://github.com/PotentialIngenuity/petio-unraid>

![](/files/-MWprb4H9vyHZwI0PCUh)

* Click on`Add Container`

![](/files/-MWprb4E4KPGScFTEoAn)

* Configure the container like all the others on unRAID.

![](/files/-MWpttfjhv3BhH3WRrgZ)


# Windows

If you notice any mistakes that need to be corrected, please reach out on Discord!

## Installation

The recommended installation order is to choose which way you prefer to run Mongo, host it locally or remotely. Secondly, we recommend you install Petio as a service so it can start automatically everytime your system boots up. We recommend either [NSSM](#nssm) or [Shawl](#shawl).

## Mongo

Petio supports two ways of connecting to a Mongo Database instance, locally or remote. We recommend the locally hosted MongoDB option.

### MongoDB Locally

* Download MongoDB Community Server [here](https://www.mongodb.com/try/download/community) (make sure to choose the latest version of 4.4.x). That version only support Windows 10 and Server 2019. If you are on older OS, you need to download Community Server Edition v4.2.
* Install MongoDB using the default instructions on screen.
* Download the latest version of [Petio](https://petio.tv/releases/latest) and decide which installation method you prefer
  * [NSSM](#nssm)
  * [Shawl](#shawl)
* Once this is complete, you can navigate to `http://<hostname>:7777/admin/` to start [configuring Petio](/configuration/first-time-setup). When you get to the MongoDB setup, instead of `mongo:27017` use `localhost:27017`.

### MongoDB Locally - On A Different Host

* Please review the [Linux guides](/install-guides/linux/debian-ubuntu#mongodb-locally-on-a-different-host) and make changes as necessary for your situation.

### MongoDB Remotely

* Register for Atlas [here](https://www.mongodb.com/cloud/atlas/register).
* Create a free cluster.

![](/files/-MWpwKzvMm2w27RFKx9r)

* Change the provider or region if you need to. It may take some time to create the cluster.

![](/files/-MWpwKzuKe3yy1gb7f_A)

* After the cluster is made, click on connect and select MongoDB Compass and follow the instructions on screen.

![](/files/-MWpwKztq-smEhPkWGz9)

* Download the latest version of [Petio](https://petio.tv/releases/latest) and decide which installation method you prefer
  * [NSSM](#nssm)
  * [Shawl](#shawl)

## Petio as a Service

First of all, download the Petio binaries from the [downloads page](https://petio.tv/downloads/) and extract the zip file to a convenient location. (We recommend at the root of your `C:` drive, i.e: `C:\Petio`.) Note that the folders from the zip file (`config` and `views` at the time of this writing) need to stay in the same folder as the binary itself.

### NSSM

* Download the latest release of [NSSM](https://nssm.cc/download).
* Extract the zip folder anywhere you want on your system. We recommend the root of your `C:\` drive on a folder called `NSSM`.
  * Add the `NSSM` folder to your Windows Path.
    * Go to Control Panel > System > Advanced System Settings
    * Click on `Environment Variables` at the bottom
    * Under `System Variables` scroll down until you see `Path` and double click on it
    * Click `New` and type `C:\NSSM`
* To start the installion of Petio as a service type:

```
nssm install petio
```

* In the `Application` tab make sure to specify the path to`Petio.exe` and then click install service.
* To start the service use:

```
nssm start petio
```

* To check if the service is up and running use:

```
nssm status petio
```

* If you later wish to remove this service use:

```
nssm remove petio
```

* Once this is complete you can navigate to `http://<hostname>:7777/admin/` to start [configuring Petio](/configuration/first-time-setup).

### Shawl

* Grab the latest release of [Shawl](https://github.com/mtkennerly/shawl/releases).
* Shawl is portable, so place it anywhere you want on your system; we recommend the root of your `C:\` drive in a folder called `Shawl`.
* Open up an administrator command prompt and navigate to the directory where you placed Shawl. In our case:

```
cd C:\Shawl
```

* Create a service for Petio with Shawl using the command:

```
shawl.exe add --name Petio -- "C:\path\to\petio.exe"
```

* Then, start the Petio service like so (if you used PowerShell, replace `sc` by `sc.exe`):

```
sc start Petio
```

* To stop Petio, use

```
sc stop Petio
```

* Once this is complete you can navigate to `http://<hostname>:7777/admin/` to start [configuring Petio](/configuration/first-time-setup) or by viewing the `.log` file that Shawl created for Petio in the same directory where you placed Shawl.

### Reverse Proxy

You have the ability to serve Petio behind a reverse proxy. This is inherently more secure as you are not having to punch holes through your router's firewall or your Windows' firewall for every service you want to access remotely. By serving services behind a reverse proxy you are filtering all the traffic to ports 80/443. We recommend you read over our reverse proxy section. We have some helpful examples and there is even one [specific to Windows](/reverse-proxy/caddy).

## Updating Petio

* Download latest binaries from [here](https://petio.tv/releases/latest/).
* Stop Petio or the Petio service.
* Replace the "views" folder and "petio-win" with contents from the zip you downloaded.
* Now you're all done. Just fire up Petio again.


# First Time Setup

If you notice any mistakes that need to be corrected, please reach out on Discord!

## Step 1

Click `Login With Plex` and follow the steps to log in.

![](/files/-MWprb453i_hq_2CUUhR)

## Step 2

After you log in with Plex you will need to specify your Petio specific admin credentials, by default it uses your Plex username and email but you still need to specify your own password.

![](/files/-MWprb46qEhH0I-CW4fW)

## Step 3

After setting up your credentials, you need to pick your Plex server.

![](/files/-MWprb47sUFzF9kK5oUp)

## Step 4

Once you select your server, you need to configure how Petio will connect to your database. You will either use the self-hosted MongoDB instructions or the remote hosted MongoDB database instructions for your OS.

![](/files/-MWprb48yeAtp8g6dX2S)

{% hint style="warning" %}

* If you are using the MongoDB Remotely option click on `mongo://` to switch it to `mongo+srv://` and copy the connection string from Atlas, without the `mongo+srv://` and `/test`.&#x20;
* Replace the `<password>` with your password. The syntax should be user:<password@cluster.mongodb.net>.
  * If your password contains any special characters you should encode it using [URLEncoder](https://www.urlencoder.org/).
    {% endhint %}

## Step 5

If you configured everything correctly, the last screen should look like this.

![](/files/-MWprb49WdpL-gAaBRIl)

## Step 6

Once the last step is finished, you will be presented with a login screen. Use your Plex username and the password you set up on Step 2. You can now get started with configuring Radarr, Sonarr and start requesting!


# General Settings

If you notice any mistakes that need to be corrected, please reach out on Discord!

## Settings

The settings tab is where you will configure your general settings such as email, webhooks, base path (subdirectory), etc.

### Base Path

A base path is helpful if you are wanting to serve Petio behind a reverse proxy using the subdirectory method, otherwise known as a `base URL`, `base path`, or `subdirectory`. Please see our reverse proxy section for more information and examples.

### User Login

This setting will determine which login method is used to login to Petio. For the admin panel you will **always** need a username/password if you don't use Plex oAuth.

However, for the user panel you can specify `Standard Login` or `Fast Login`. The difference is that with `Fast Login` your users will only need to specify their Plex email/username whereas with `Standard Login` they will need to use your Plex email/username and password.

### Popular Content On Plex

{% hint style="danger" %}
This feature **requires** Plex Pass&#x20;
{% endhint %}

Adds the most popular Movies and TV Shows on Plex in the last 30 days based on user plays. It shows up when you click on the Movies/TV section

![](/files/-MWqgdJrcTcRGUCGr50C)

![](/files/-MWqgcVJxzwiY3A_xFAF)


# Radarr

If you notice any mistakes that need to be corrected, please reach out on Discord!

You can add multiple Radarr servers to your Petio instance. This will show you how to connect an existing Radarr server to Petio.

{% hint style="warning" %}
We only support Radarr V3.
{% endhint %}

{% hint style="info" %}
In the screenshots below we assume you are using locally accessible docker containers that are on the same docker network as Petio.
{% endhint %}

## Step 1

Click on `Add New`

![](/files/-MWprb42BmhEvdK9PBuI)

## Step 2

After clicking `Add New` you need to specify all your Radarr settings and give it a friendly name you can recognize. Your `host` and `port` fields will vary depending on what installation method you chose.

If you are hosting Radarr behind a reverse proxy and have configured a base URL, you need to specify it on the `URL Base` field. If this all sounds like alien speak, you don't have to write anything there.&#x20;

{% hint style="danger" %}
Make sure that the URL Base field has a preceding slash like `/radarr`
{% endhint %}

You can obtain your **R**adarr API key by going to your Radarr instance and clicking on `Settings > General`.

![](/files/-MWprb43q7pmwe2RCZsM)

## Step 3

Hit `Test` to make sure you configured it correctly. You will not be able to configure your `Profile` and `Path` without testing the connection ahead of time. You should see a little message on the bottom right that says `Radarr Test Connection success!`

![](/files/-MWprb44YpsnzN7GQPZw)

Once you are done hit `Save` and you are ready to requests movies!


# Sonarr

If you notice any mistakes that need to be corrected, please reach out on Discord!

You can add multiple Sonarr servers to your Petio instance. This will show you how to connect an existing Sonarr server to Petio.

{% hint style="warning" %}
We support all Sonarr versions for now. V2 support will be dropped soon
{% endhint %}

{% hint style="info" %}
In the screenshots below we assume you are using locally accessible docker containers that are on the same docker network as Petio.
{% endhint %}

\*\*\*\*

## Step 1

Click on `Add New`

![](/files/-MWprb4AYV-tyCIAHSg7)

## Step 2

After clicking `Add New` you need to specify all your Sonarr settings and give it a friendly name you can recognize. Your `host` and `port` fields will vary depending on what installation method you chose.

If you are hosting Sonarr behind a reverse proxy and have configured a base URL, you need to specify it on the `URL Base` field. If this all sounds like alien speak, you don't have to write anything there.

{% hint style="danger" %}
Make sure that the URL Base field has a preceding slash like `/sonarr`
{% endhint %}

You can obtain your Sonarr API key by going to your Sonarr instance and clicking on `Settings > General`.

![](/files/-MWprb4BpjvYluzbWpF9)

## Step 3

Hit `Test` to make sure you configured it correctly. You will not be able to configure your `Profile` and `Path` without testing the connection ahead of time. You should see a little message on the bottom right that says `Sonarr Test Connection success!`

![](/files/-MWprb4CAe6MxVl0qcFU)

Once you are done hit `Save` and you are ready to requests TV Shows!


# Console

If you notice any mistakes that need to be corrected, please reach out on Discord!

The console can be used to view the logs live. You can filter by `INFO`, `WARNING`, `ERROR` and `VERBOSE`.


# User Profiles

If you notice any mistakes that need to be corrected, please reach out on Discord!


# Filters

If you notice any mistakes that need to be corrected, please reach out on Discord!

Filters are way you can control how your requests get handled. Think of it like another layer of automation on top of Radarr/Sonarr.&#x20;

Let's say you like to separate your media based on age rating, either you have kids or know someone with kids. Filters allow you to be granular about where requested "kid content" gets placed including Radarr/Sonarr server (if you have multiple ones configured), path, and/or tag. You can use the available operands `AND`/`OR`to determine how many things must be evaluated true before Petio sends the request to Sonarr/Radarr with the specified paths, profile, and/or tags.

Filters can be used with age ratings, genre, language, and keywords! We hope to revamp filters in the future so stay tuned!&#x20;

For those of you using `AND`/`OR` operands for the first time I'll provide a quick explanation of each. Any one of the `OR` conditions can trigger a match whereas an `AND` operator must always be true for the entire filter to match. Most of the time, you want to use `OR` instead of `AND` otherwise, you'll stare at your screen wondering why it isn't working. If you have questions how to configure filters, please stop by our [Discord](https://discord.gg/bseGmrUd3N) and ask some questions!

### Age Ratings Filter Example

![](/files/-MWqkqZqiZNHHjOwHg06)

![](/files/-MWqkpq_k580pE6tqi46)

### Anime Filter Example

![](/files/-MWtLMBbaBq5KIR-IUuu)

### Sonarr Language Filter Example

* Setup a language profile in sonarr.

![](/files/-MWtNN_3qEkzEp20j0wm)

* Add the language filter in Petio.

![](/files/-MWtNXUeOlqw1eE6pb9H)


# Notifications

If you notice any mistakes that need to be corrected, please reach out on Discord!

### Email

You can configure these email settings in order to get notifications when users request content and when content you've requested is marked available by Plex.

#### From Address

Modify this if you want the email to show up as something other than who you authenticate as. For example `petio@myemail.com` or `brucewillis@myemail.com`

#### Username

This is the username you use to log in. Most of the time is your actual email or sometimes you can use just the first part without specifying `@myemail.com`

#### Password

I think I don't really have to do write what a password is, do I? However, this is the password you use to log in to the email account. Not your Plex password, not your Petio password and not the password to your bank. I really hope you aren't using the same password across those 3 services...

{% hint style="warning" %}
**NOTE:** If you are using Gmail make sure [to read ](https://support.google.com/accounts/answer/185833)what to do if you use 2FA on your account.
{% endhint %}

#### SMTP Server

This one is all dependent on who your provider is, if you self host your own email server I hope you know your SMTP server.&#x20;

#### Port

The port is again dependent on your provider. Below you can find a table for the most common providers with SMTP server, and their SSL/TLS ports

| Mail Provider           | SMTP Server          | TLS Port | SSL Port |
| ----------------------- | -------------------- | -------- | -------- |
| Gmail                   | smtp.gmail.com       | 587      | 465      |
| GSuite/Google Workspace | smtp-relay.gmail.com | 587      | N/A      |
| SendGrid                | smtp.sendgrid.net    | 587      | 465      |
| MailGun                 | smtp.mailgun.org     | 587      | N/A      |

{% hint style="info" %}
Depending on what port you pick you might need to be sure **to not check** the box that says "Use Secure"
{% endhint %}

### Webhooks

#### Discord

{% hint style="info" %}
We assume you either have your own Discord or are in one where you have adminitrator permissions to perform these steps
{% endhint %}

* Create a new channel or use an existing one.
* Click `Edit Channel`.
* Click `Integrations`.
* Click `Webhooks`.
* Click `New Webhook`.
* Give it a `Name` and select the `Correct channel` then copy `Webhook URL` and save.
* Go to Petio then Admin panel -> Settings. Scroll down until you find `Discord`.
* Paste the `Webhook URL` -> Test -> Save.

### Telegram


# Reverse Proxy Basics

If you notice any mistakes that need to be corrected, please reach out on Discord!

A good ELI5 explanation for a reverse proxy server is to think of it as a single point of entrance for your network as opposed to multiple points of entrance. It checks requests coming in through  ports 80/443 - or whatever port you might specify differently - and directs those requests to the correct server such as Petio, Radarr or Sonarr. The reason why this is more secure is because rather than randomly punching holes in your firewall for *each* service, you are only forced to open up 1 or 2 ports that handle all the traffic.

We recommend you read [LinuxServer.io's guide ](https://docs.linuxserver.io/general/swag)on how to set up their SWAG container which contains all the necessary tools for a reverse proxy at home.


# Caddy

If you notice any mistakes that need to be corrected, please reach out on Discord!

## Caddy For Windows

* Download the newest release from [here](https://caddyserver.com/v2).
* Create a folder named `Caddy` on root of the `C:\` drive or where you got Windows installed.
* Extract the Caddy zip in the folder you just created.
* In the new Caddy folder make another folder called `logs`.

### Make a Caddy File

* Create a new text file, rename it to `Caddyfile` and make sure it doesn't have an extension.
* In the `Caddyfile` paste:

```
example.ddns.net {
    encode gzip
        log {
            output file C:\Caddy\logs\petio.log {
            roll true               # Rotate logs, enabled by default
            roll_size_mb 5          # Set max size 5 MB
            roll_gzip true          # Whether to compress rolled files
            roll_local_time true    # Use localhost time
            roll_keep 2             # Keep at most 2 log files
            roll_keep_days 7        # Keep log files for 7 days
            }
        }
    reverse_proxy localhost:7777
}
```

* Remember to change `localhost` and `port` accordingly.

### Start Caddy

{% hint style="info" %}
You will need the bat file for both manuall and service.
{% endhint %}

* You have two ways to run Caddy.

  * You can do it manually by creating a bat file:

  ```
  cd C:\Caddy
  Caddy run'
  ```

  * You can run it as a service. Just follow the [NSSM](/install-guides/windows#nssm) or [Shawl](/install-guides/windows#shawl) guides.

### Port Forwarding

* Open port `80` and `443`. \
  If you don't know how to port forward you should check out [Portforward.com](https://portforward.com/router/) and find your router.

### Firewall

* Open port `80` and `443` in your firewall.\
  To open Windows Firewall, go to the Start menu, select Run, type `WF.msc` and then select OK.
* Now click on Inbound Rules, then on the right side you want to click new rule.
* Select Port click next.
* Select TCP and type inn `80, 443` then next.
* Allow the connection and hit Next. Then just choose a name like "Caddy".

### DNS

* Now you need to get DNS redirect set up. \
  Some examples of services you can use are [noip](https://www.noip.com/) or [DuckDNS](https://www.duckdns.org/). Just make sure you set the record type as “DNS Host (A)”.

##


# NGINX

If you notice any mistakes that need to be corrected, please reach out on Discord!

## NGINX Subdomain example

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

    # Make sure you create a CNAME with your domain registrar
    server_name petio.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    location / {
    
        # Delete the line below if you aren't using LSIO's SWAG container
        # or if you don't have a file called "proxy.conf"
        include /config/nginx/proxy.conf;

        # Delete the line below if you aren't using Docker DNS
        resolver 127.0.0.11 valid=30s;

        # Change the word petio below to the IP 
        # of where Petio is installed if you aren't using Docker DNS
        set $upstream_app petio;

        # You can leave the next 3 lines as is,
        # unless you are using a different port 
        # or you are somehow using HTTPS internally
        set $upstream_port 7777;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }

    # This is optional and only if you want to protect your `/admin` endpoint
    # with some sort of auth in front of it.
    # No auth example is being provided
    
    location /admin/ {
    
        # Delete the line below if you aren't using LSIO's SWAG container
        # or if you don't have a file called "proxy.conf"
        include /config/nginx/proxy.conf;
        
        # Delete the line below if you aren't using Docker DNS
        resolver 127.0.0.11 valid=30s;

        # Change the line below to the IP 
        # of where Petio is installed if you aren't using Docker DNS
        set $upstream_app petio;
        
        # You can leave the next 3 lines as is,
        # unless you are using a different port 
        # or you are somehow using HTTPS internally
        set $upstream_port 7777;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
    }
}
```

## NGINX Subdirectory Example

Make sure you've set a [base path](/configuration/general-settings#base-path).

```
location ^~ /petio {

    # Delete the line below if you aren't using LSIO's SWAG container
    # or if you don't have a file called "proxy.conf"
    include /config/nginx/proxy.conf;
    
    # Change the word petio below to the IP 
    # of where Petio is installed if you aren't using Docker DNS
    set $upstream_app petio;
    
    # You can leave the next 3 lines as is,
    # unless you are using a different port 
    # or you are somehow using HTTPS internally
    set $upstream_port 7777;
    set $upstream_proto http;
    proxy_pass $upstream_proto://$upstream_app:$upstream_port;
}
```

## NGINX Proxy Manager

Expose web services on your network · Free SSL with Let's Encrypt · Designed with security in mind · Perfect for home networks

* Install the latest version of [NGINX Proxy Manager](https://nginxproxymanager.com/#quick-setup/).
* Click on "Proxy Hosts" on the dashboard.
* Click on "Add Proxy Host".

### Details Tab

* Domain names: add your domain. For example: `example.duckdns.org`.
* Scheme: keep at `http`.
* Forward hostname/IP: add your host IP. For example: `192.168.X.X` or `localhost`.
* Forward port: add the port for petio i.e.`7777`.
* Access list: set to `Publicly Accessible`.

![](/files/-MWprb407KyL2DbSFIa-)

### SSL Tab

* SSL Certificate: Select "Request a new SSL Certificate".
* Enable "Force SSL"
* Email address for Let's Encrypt: type in the email you want to use for registration on Let's encrypt.
* Click on the "I Agree to the Let's Encrypt Terms of Service" box.
* Hit save and your all done.&#x20;

![](/files/-MWprb41JgIvUEPgjlIe)

Now you should be able to access Petio from your domain name.


# Traefik (v2)

If you notice any mistakes that need to be corrected, please reach out on Discord!

## Traefik Subdomain Example

Assuming a basic setup like [the one in the Traefik documentation](https://doc.traefik.io/traefik/user-guides/docker-compose/acme-dns/) where an entrypoint called `websecure` exists, adding these labels down below to the Petio service should be the minimum that's needed to reverse proxy Petio.

```yaml
labels:
    - "traefik.enable=true"
    ## HTTP Routers
    - "traefik.http.routers.petio-rtr.entrypoints=websecure"
    - "traefik.http.routers.petio-rtr.rule=Host(`petio.mydomain.com`)"
    - "traefik.http.routers.petio-rtr.tls=true"
    ## HTTP Services
    - "traefik.http.routers.petio-rtr.service=petio-svc"
    - "traefik.http.services.petio-svc.loadbalancer.server.port=7777"
```


# FAQ

![](/files/-MWprb4Dk9ggDYzHExIu)

## Docker

### Petio Crashes On Container Startup

#### Error Example #1

```bash
| (node:8) UnhandledPromiseRejectionWarning: Error: getaddrinfo ENOTFOUND api.themoviedb.org
|     at GetAddrInfoReqWrap.onlookup [as oncomplete] (dns.js:67:26)
| (node:8) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 3)
| (node:8) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'results' of undefined
|     at trending (/app/api/tmdb/trending.js:28:30)
|     at processTicksAndRejections (internal/process/task_queues.js:93:5)
| (node:8) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 4)
| 2021-03-28 20:42:28 error: TypeError: Cannot set property 'timestamp' of null
petio exited with code 1
```

* Normally this is caused by the container trying to resolve an IPv6 address for `api.temoviedb.org`. To verify if this is the issue:
  * `docker exec  -it petio sh`
    * `nslookup api.themoviedb.org`
* To fix this issue, go back to when you first configured Docker and remember if you made some custom changes. This is not a Petio issue but rather an issue on your configuration.

## Linux

## MacOS

## unRAID

## Windows


# Petio Pre-Release Workflow For Testers

## Installation & First Time Setup

1. Wipe all **test** mongo/petio config folders
2. Pull latest `preview` tag and recreate Petio container
   * Optional: Create your appdata folders ahead of time to prevent permissions issues
3. Go to `http://hostname:port` and verify Petio redirects you to `/admin` when no `config.json` is present
4. Go through the initial setup and verify it completes without issues.

## Admin Panel Login

1. Log in to the admin panel with your credentials.
   * Errors?
2. Log in to the admin panel with Plex oAuth
   * Errors?

## Dashboard

1. Go to `Dashboard`
   * Do you have Plex Pass?
     * Yes
       * Are Plex Pass features available?
     * No
       * Do you see any errors?

## Requests

1. Click on `Requests`
   * Errors?

## Issues

1. Click on `Issues`
   * Errors?

## Reviews

1. Click on `Reviews`
   * Errors?

## Users

1. Click on `Users`
   * Create a new user profile with auto approve and no quota
     * Errors?
   * Create a new user profile with auto approve and quota
     * Errors?
   * Create a new user profile without auto approve and a quota
     * Errors?
   * Create a new user profile without auto approve and no quota
     * Errors?
   * Create a new user profile and set it as a default
     * Errors?
   * Bulk Edit and assign new user profiles to multiple users
     * Errors?

## Settings

1. Click on `Settings`
   * Errors?

### General

1. Under `General`
   * Test Plex connection
     * Errors?
   * Test email notification
     * Errors?
   * Test setting a base path
     * Restart Petio
       * Try to access admin panel by going to `http:\\hostname:port/petio/admin`
         * Errors?
   * Test `Standard` and `Fast` login methods
     * Errors?
   * Test enabling and disabling `Popular content on Plex`
     * Do you have Plex Pass?
       * Yes
         * Is Popular Content available when enabled and unavailable when disabled?
       * No
         * Do you see any errors when clicking on Movies/TV Shows?

### Radarr

1. Click on `Radarr`
   * Errors?
   * Test adding a new Radarr server
     * Errors?

### Sonarr

1. Click on `Sonarr`
   * Errors?
   * Test adding a new Sonarr server
     * Errors?

### Filters

1. Click on `Filters`
   * Errors?
   * Test creating filters
     * Test your filters and report back any filters with logic errors

### Console

1. Click on `Console` and verify you can filter through logging levels

## Request Content

1. Request content
   * Do notifications work as intended?
   * Are requests getting auto approved if set to be?
   * Are requests getting default values?

## General Testing

1. Report any typo, general errors you saw, wiki updates, etc.