Getting Started

• 1: Compile from source code
• 2: Installation on Linux
• 3: Installation on Windows
• 4: Run with Docker

1 - Compile from source code

This guide explains how to compile PersonalMediaVault from source code.

Requirements

You will need the following tools installed on your system to compile PersonalMediaVault:

• Git
• Golang, latest stable version
• NodeJS, latest stable version
• Rust, latest stable version

Install FFMpeg (Dependency)

PersonalMediaVault uses FFmpeg as a dependency to encode media, generate thumbnails among other things.

Download it from the official website and install it into your system.

Make sure the ffmpeg and ffprobe binaries are located inside /usr/bin. If they are not, please, set up the following environment variables in your system:

Clone repository

Clone the PersonalMediaVault repository with the following command:

git clone https://github.com/AgustinSRG/PersonalMediaVault
cd PersonalMediaVault

Compile backend

Navigate to the backend folder and run the compilation script:

cd backend
./build-production.sh
cd ..

The result will be a binary named pmvd. Copy it into /usr/bin

Compile backup tool

Navigate to the backup-tool folder and run the compilation script:

cd backup-tool
./build-production.sh
cd ..

The result will be a binary named pmv-backup. Copy it into /usr/bin

Compile launcher (console version)

Navigate to the launcher folder and run the compilation script:

cd launcher
./build-production.sh
cd ..

The result will be a binary named pmv. Copy it into /usr/bin

Compile launcher (GUI version)

Navigate to the launcher-gui folder and run the compilation script:

cd launcher-gui
./build-production.sh
cd ..

The result will be a binary named pmv-gui. Copy it into /usr/bin

Compile frontend

Navigate to the frontend folder and run the compilation script:

cd frontend
npm install
npm run build
cd ..

The result will be a folder named dist. Copy its contents into /usr/lib/pmv/www

If you prefer to store the frontend into another path, make sure to set the following environment variable in your system:

Creating and running a vault

In order to create, or open a vault, run the launcher command:

pmv ./my_vault

This command will create a new vault on that folder, asking you for the initial username and password.

After it’s created, it will ask you for the port to run the server, and will start it, opening your default browser.

2 - Installation on Linux

This guide explains how to download and install PersonalMediaVault on a Linux system, using one of the provided installation packages

Depending on your Linux distribution, we offer several packages.

Debian, Ubuntu or other Debian based Linux distribution

For Debian-based Linux distributions, download the DEB package (personalmediavault_{VERSION}_amd64.deb) from Releases.

Install the package, with apt or with your graphical package manager.

You can also install it directly from the PPA repository (built automatically with GitHub actions):

# Download the public key
curl -s --compressed "https://agustinsrg.github.io/PersonalMediaVault/KEY.gpg" | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/pmv.gpg >/dev/null

# Add the APT list file
sudo curl -s --compressed -o /etc/apt/sources.list.d/pmv.list "https://agustinsrg.github.io/PersonalMediaVault/pmv.list"

# Update APT lists
sudo apt update

# Install the package
sudo apt install personalmediavault

After it’s installed, you can run the launcher with pmv /path/to/vault or the graphical launcher by searching for “PersonalMediaVault” in your application menu.

Fedora Linux

For Fedora-based Linux distributions, download the RPM package (personalmediavault-{VERSION}.x86_64.rpm) from Releases.

Install the package, with dnf or with your graphical package manager.

After it’s installed, you can run the launcher with pmv /path/to/vault or the graphical launcher by searching for “PersonalMediaVault” in your application menu.

Arch Linux

For Arch-based Linux distributions, download the PKG.TAR.ZST package (personalmediavault-{VERSION}-x86_64.pkg.tar.zst) from Releases.

Install the package, with pacman:

sudo pacman -U personalmediavault-{VERSION}-x86_64.pkg.tar.zst

After it’s installed, you can run the launcher with pmv /path/to/vault or the graphical launcher by searching for “PersonalMediaVault” in your application menu.

Other Linux distribution

For any other Linux distribution, you can download the TAR.GZ package (personalmediavault_{VERSION}_amd64.tar.gz) from Releases.

Uncompress it, and run the installation script (install.sh) with administration privileges:

sudo ./install.sh

After it’s installed, you can run the launcher with pmv /path/to/vault or the graphical launcher by searching for “PersonalMediaVault” in your application menu.

KDE service menu

If you are using a Linux distribution, and KDE as your desktop environment, you can get the same context menu options to open vaults that are installed in the Windows package.

Create the file ~/.local/share/kio/servicemenus/pmv-open.desktop with the following contents:

[Desktop Entry]
Name=Open with PersonalMediaVault
Type=Service
ServiceTypes=KonqPopupMenu/Plugin
MimeType=inode/directory
Actions=openWithPmv

[Desktop Action openWithPmv]
Name=Open with PersonalMediaVault
Name[es]=Abrir con PersonalMediaVault
Terminal=false
Icon=pmv
StartupWMClass=pmv
Exec=pmv-gui .

If you prefer to use the console launcher instead, use the following desktop entry:

[Desktop Entry]
Name=Open with PersonalMediaVault (Console)
Type=Service
ServiceTypes=KonqPopupMenu/Plugin
MimeType=inode/directory
Actions=openWithPmvConsole

[Desktop Action openWithPmvConsole]
Name=Open with PersonalMediaVault (Console)
Name[es]=Abrir con PersonalMediaVault (Consola)
Terminal=false
Icon=pmv
StartupWMClass=pmv
Exec=konsole --separate -e 'pmv .'

3 - Installation on Windows

This guide explains how to download and install PersonalMediaVault on a Windows system.

Download

Download the MSI installer (PersonalMediaVault-{VERSION}-x64.msi) from Releases.

The file should have a name formatted similar to PersonalMediaVault-A.B.C-x64.msi, replacing A, B and C for the major, minor and patch version number respectively.

Make sure to check the file hash with Powershell and compare it to the provided hash on GitHub.

Installing

Once downloaded, run the installer and follow the steps.

The installer should take care of everything for you, installing all the dependencies and placing the binaries in the Program Files folder.

Creating and running a vault

The installer will add an option to the file explorer to open a folder with PersonalMediaVault.

Create a new folder, and use that option to open with PersonalMediaVault.

That will open the launcher, asking you for an initial username and password for your vault.

After the vault is created, it will ask you for a port to run the server, and will start it, opening your default browser.

4 - Run with Docker

This guide explains how to run PersonalMediaVault with Docker.

Pull image

First, select a Docker repository and pull the image

• Docker Hub
• GitHub Packages

Here is an example, if you choose Docker Hub:

docker pull asanrom/pmv

Setup vault

Create a folder where you wish to install the vault, and create a file named docker-compose.yml, with the following content:

services:
  pmvd:
    hostname: "pmvd"
    image: "asanrom/pmv"
    ports:
      - "${VAULT_PORT}:8000"
    restart: unless-stopped
    volumes:
      - ${VAULT_PATH:-./vault}:/vault
      - ${VAULT_SSL_PATH:-./ssl}:/ssl:ro
    environment:
      - USING_PROXY=${USING_PROXY:-NO}
      - VAULT_INITIAL_USER=${VAULT_INITIAL_USER:-admin}
      - VAULT_INITIAL_PASSWORD=${VAULT_INITIAL_PASSWORD:-changeme}
      - SSL_CERT=${SSL_CERT:-}
      - SSL_KEY=${SSL_KEY:-}
    command: --daemon
      --clean
      --port 8000
      --skip-lock
      --vault-path /vault
      --cache-size ${VAULT_CACHE_SIZE:-1024}
      ${VAULT_EXTRA_OPTIONS:-}

Also, create a .env file, with the following content (modify the configuration depending on your needs):

####################################
# PersonalMediaVault configuration #
####################################

# Listening port
VAULT_PORT=8000

# Path where the vault will be stored
VAULT_PATH=./vault

# SSL (recommended)
#
# Running the vault with HTTP is the most secure option
# Obtain a key and a certificate for your domain
#
# Set VAULT_SSL_PATH to the path where the key and the certificate are stored
# This path will be mapped to /ssl in the container
# Set SSL_KEY and SSL_CERT to the key and certificate chain files respectively
# The files must be in the /ssl path (eg: /ssl/certificate.pem) and in PEM format

VAULT_SSL_PATH=./ssl

#SSL_KEY=/ssl/key.pem
#SSL_CERT=/ssl/certificate.pem

# Reverse proxy
#
# Sometimes is better to use a reverse proxy (line NGINX)
# as the frontend and forward the requests to the daemon
#
# If you are using it, set USING_PROXY to YES in order for
# the daemon to change the way it resolves the IP addresses of clients

USING_PROXY=NO

# Initial vault user
#
# If the vault has no users, an initial user will be created
#
# Set VAULT_INITIAL_USER and VAULT_INITIAL_PASSWORD
# for the username and password respectively
#
# Make sure to change them the first time you log into the vault.

VAULT_INITIAL_USER=admin
VAULT_INITIAL_PASSWORD=changeme

# Cache size
# You can modify it to accelerate the read speed
# but will also result in higher memory usage
# The recommended value is 1024

VAULT_CACHE_SIZE=1024

# Extra options
#
# You can set the following extra options,
# separating them with spaces:
#
#   --log-requests - Enables request logging
#   --debug - Enables debug logging (useful for troubleshooting)
#   --fix-consistency - Fixes vault consistency at startup (takes some time)
#   --recover - Recovers non-indexed media assets.

VAULT_EXTRA_OPTIONS=--log-requests

Check the server options for more information of all the available options to run the server.

Running the vault

In order to run the vault, run Docker compose:

docker compose up -d

Go to http://localhost to check out your vault. You can login with the credentials you specified in VAULT_INITIAL_USER and VAULT_INITIAL_PASSWORD.

Change your password, and possibly username, and start using your vault.

Upgrading the image

If you want to upgrade the image in order to use the latest version, wun:

docker compose pull

Then, to restart the vault, run:

docker compose up -d

Stopping the vault

If you want to stop the vault server, run the following command:

docker compose down