INSTALL GUIDE: PhotoPrism in a Jail on TrueNAS Core 13.0
There have been a few threads about the difficulty of setting up PhotoPrism in a jail on TrueNAS Core. After a lot of work, I've managed to get it working, so I thought I would document it here to help others.
These instructions are tested and working as of mid-February 2023. I will try to add updates if things change in future.
Changelog:
- 16 Jan 23: First version
- 18 Feb 23: Clarify drive mounting options; add NAT config; add software for RAW conversion; add existing photo collection to originals folder; add extra startup command-line args in sysrc.
You may notice that some of the commands below differ slightly from various other recipes you might find on the web. I didn't want to bog down the instructions with lots of explanation, but if you want to know why something is the way it is, reply to this thread and I'll try to explain!
OK, let's get started!
Plan your photo storage
Before you set up the jail, think about how you want to lay out the storage of PhotoPrism's working data and your photos. By default, PhotoPrism stores all its data and photos in a single folder heirarchy like this:
Code:
PHOTOPRISM_STORAGE_ROOT/
/albums/
/backup/
/cache/
/config/
/import/
/originals/ <-- your photo files are stored here
/serial/
/sidecar/
/users/
It makes sense to store this whole folder heirarchy on a separate dataset mounted by the jail, rather than in the jail itself. That way, you can easily update, delete or recreate the jail without losing any precious data or photos. The instructions below assume that this PhotoPrism dataset will be mounted at
/mnt/photos If you want to import all your photos into PhotoPrism and let it manage and organise them for you, then you don't need to do anything more.
Of course, you may already have your photos organised and stored elsewhere on your TrueNAS server in another dataset and you just want PhotoPrism to index and display those photos without touching them. In that case, you can optionally mount your existing photos dataset into the
originals/ folder and I give additional instructions for doing that at the end.
By default, PhotoPrism will use SQLite to store its index, which is fine for small photo collections. PhotoPrism's index can optionally be stored in MariaDB for improved performance and I give optional instructions for this below.
If you use MariaDB, then you will have to remember to backup the database before deleting and recreating the jail. Instructions for doing this are on the
PhotoPrism website.
Configure the Jail
PhotoPrism has not been updated for FreeBSD 13.x-RELEASE yet, so it needs its own jail running 12.x-RELEASE.
Be careful not to accidentally upgrade this jail to 13.x later on!
In the TrueNAS web interface, choose
Jails from the sidebar and click
Add
Set the following options:
- Name: photos
- Release: 12.4-RELEASE
- Type: Basejail
- Networking: Configure to suit your network. It is better to avoid DHCP - either use NAT, in which case <ip-address> below will be the address of your TrueNAS server, or use VNET, in which case <ip-address> will be the one that you choose
Click
Next then
Submit, wait for the installation to finish and then click
Edit
Make sure that
Auto-start is ticked
OPTIONAL: Configure NAT
Scroll down and expand
Network Properties
Tick
NAT Port Forwarding
Set the following options:
- Protocol: tcp
- Jail Port Number: 2342
- Host Port Number: 2342
Click
Add
Mount the PhotoPrism storage dataset
Click
Save then
Mount Points
Click
Actions then
Add
For the
Source, browse to
/path/to/photoprism/dataset
For the
Destination, browse to
/path/to/jail/mnt and type "/photos" after it.
Click
Submit
IMPORTANT: If you optionally want to add your existing photos dataset, don't do that yet! See the extra instructions at the end!
Initial Setup
The rest of the setup is done entirely in the jail's console. If you are copying and pasting commands into the TrueNAS web console, do it one line at a time, and use
SHIFT-CTRL-V to paste.
Go to the
Jails view, expand the photos jail, click
Start and then
Shell
Update the package manager:
pkg update
pkg upgrade
Install my favourite text editor
pkg install micro
OPTIONAL: Configure MariaDB
Install packages:
pkg install mariadb106-server mariadb106-client
Configure startup parameters:
sysrc mysql_enable="YES"
sysrc mysql_args="--bind-address=127.0.0.1"
Start mysql:
service mysql-server start
Harden the MariaDB installation:
mysql_secure_installation
In the prompts that follow:
- Hit ENTER at the root password prompt
- n - Switch to unix_socket authentication
- n - set root password (FreeBSD already keeps the root account secure anyway)
- Y - remove anonymous users
- Y - disallow remote root login
- Y - remove test database
- Y - reload privilege tables
Login to the mysql server to configure the photoprism database:
mysql -u root
Enter the following commands into the mysql prompt, one line at a time, setting your own strong password at "CHANGEME":
Code:
CREATE DATABASE photoprism
CHARACTER SET = 'utf8mb4'
COLLATE = 'utf8mb4_unicode_ci';
CREATE USER 'photoprism'@'%' IDENTIFIED BY 'CHANGEME';
GRANT ALL PRIVILEGES ON photoprism.* to 'photoprism'@'%';
FLUSH PRIVILEGES;
QUIT;
Configure PhotoPrism
Install required packages:
pkg install p5-Image-ExifTool ffmpeg libheif
Install optional packages for RAW file conversion. You will then be able to choose between them in the PhotoPrism settings page:
pkg install rawtherapee darktable
Install a working version of
libtensorflow1:
pkg add https://github.com/psa/libtensorflow1-freebsd-port/releases/download/1.15.5/libtensorflow1-1.15.5-FreeBSD-12.2-noAVX.pkg
Install the latest FreeBSD package of
PhotoPrism:
pkg add https://github.com/psa/photoprism-freebsd-port/releases/download/2022-11-18/photoprism-g20221118-FreeBSD-12.3-separatedTensorflow.pkg
Configure PhotoPrism startup parameters:
sysrc photoprism_enable="YES"
sysrc photoprism_assetspath="/var/db/photoprism/assets"
sysrc photoprism_storagepath="/mnt/photos/"
sysrc photoprism_defaultsyaml="/mnt/photos/options.yml"
OPTIONAL: If you want photoprism to run without user authentication (ie without asking for a username and password in the web interface):
sysrc photoprism_auth_mode="public"
OPTIONAL: If you want to add extra command line arguments (e.g. if you want to enable extra features after sponsoring PhotoPrism
)
sysrc photoprism_args="--something --something-else"
Edit a file called
/mnt/photos/options.yml:
micro /mnt/photos/options.yml
Code:
# options.yml
---
AuthMode: public #[OPTIONAL]
AssetsPath: /var/db/photoprism/assets
StoragePath: /mnt/photos
OriginalsPath: /mnt/photos/originals
ImportPath: /mnt/photos/import
# The following lines are only needed if you set up the
# optional MariaDB server
DatabaseDriver: mysql
DatabaseName: photoprism
DatabaseServer: "127.0.0.1:3306"
DatabaseUser: photoprism
DatabasePassword: CHANGEME
...
Type CTRL-S to save the file, and CTRL-Q to quit the editor
For a full list of options that can be added to
options.yml, see:
https://docs.photoprism.app/getting-started/config-files/
Be aware that settings given as command line options or as environment variables overrides the settings in
options.yml
Set permissions for the "photoprism" user on the mounted storage:
chown -R photoprism:photoprism /mnt/photos
Test run PhotoPrism
Run PhotoPrism as the "photoprism" user to set the admin password:
su -m photoprism -c 'photoprism --defaults-yaml /mnt/photos/options.yml passwd'
Run PhotoPrism interactively as the "photoprism" user to test that it works:
su -m photoprism -c 'photoprism --defaults-yaml /mnt/photos/options.yml start'
Check you can access the web page at:
http://<ip-address>:2342
Once you've confirmed that it's working, don't add any photos at this stage - just close the web page again and press CTRL-C in the console to exit PhotoPrism
Start and use PhotoPrism
If all went well above, start the PhotoPrism service:
service photoprism start
Your Photoprism server should be permanently available at:
http://<ip-address>:2342
Enjoy!
OPTIONAL: Mount an existing photos dataset
If you have an existing dataset containing your photos that you want to mount into the jail, then do that now. Waiting until this point means that PhotoPrism is set up with the right permissions and folder structure to mount the photos into.
Exit the console:
exit
Back in the Jails view, expand the "photos" jail and click
Stop, then
Mount Points
Click
Actions then
Add
For the
Source, browse to
/path/to/existing/photos/dataset
For the
Destination, browse to
/path/to/jail/mnt/photos then type "/originals" after it
If you don't want PhotoPrism to be able to make changes to your photos dataset, you can tick the
Read-Only option.
Then click
Submit
NOTE: even though the
originals folder already exists in the jail, you won't be able to browse to it directly because the jail is stopped and the photoprism dataset is therefore not mounted and accessible. If you follow the above instructions it will all work in the end, though!
In the Jails view, expand the "photos" jail and click
Start
Open the PhotoPrism web page at:
http://<ip-address>:2342
In the left sidebar, click
Settings and under the
LIBRARY tab, make any necessary changes to the Index and Stacks options to suit your preferences.
Then, to start the actual indexing of your photos, click
Library in the left sidebar. Under the
INDEX tab, make sure "All originals" is selected in the drop-down list, tick
Complete Rescan and then click
Start.
If you have a large photo collection, the initial indexing will take a long time, but after a short time you should be able to see your photos begin to appear in the
Search page.
