Debugging on Unraid

[mrm]

If you’re running PhotoStructure on an Unraid box and having issues:

First off, sorry that it didn’t just work out of the box for you!

Use the official template

Make sure you’re using the latest official docker template in Community Applications:

No images show up

If your home page is empty, navigate to the About page and look at the “health checks” section: you may see a warning: Only 4 GB are available on /.

PhotoStructure pauses the import process if the disk space for the library is limited. This health check prevents PhotoStructure from filling up a volume, which can cause issues if the volume is a system disk.

There are several solutions:

1. Allocate more disk space to your library volume. This is the best solution.
2. Reduce the minimum disk free that PhotoStructure requires. This is controlled via the minDiskFreeGb setting, which defaults to 6. (example env: PS_MIN_DISK_FREE_GB=4)
3. Disable this test altogether via the setting healthCheckFreeSpace. (example env: PS_HEALTH_CHECK_FREE_SPACE=false)

Check cache pool

Several users have found problems when using Unraid’s cache pool for their library storage. No and Prefer seem to work OK, and Yes is problematic.

If your library is on local disk, tell PhotoStructure:

Go to the docker tag in the Unraid web UI, click the PhotoStructure icon by the docker container, and click Edit:

1. Click “Add another Path, Port, Variable, …”
2. Select “Variable”
3. For Name and Key, enter PS_FORCE_LOCAL_DB_REPLICA
4. For Value, enter false
5. Click [ ADD ], then [ APPLY ].

(I will make this the default value in the template soon!)

See more about this setting here.

Check the logs

Go to the docker tag in the Unraid web UI, click the PhotoStructure icon by the docker container, and click Edit. Click “Show more settings…”, and change Logging level to debug:

Click [ APPLY ]. Then return to the Docker tab, click the PhotoStructure icon, and click Console.

In the window popup, type ./photostructure logtail and hit return:

Look for warn or error log entries.

Be sure to set this back to warn or error after you’ve got everything working: debug logging impacts performance.

See more about logging here.

Still stuck?

If this page doesn’t get you going, please leave a comment here or pop into our Unraid discord and ask for help.

[tkohhh]

I may be a bit slow, but I still have a hard time understanding what you mean by " If your library is on local disk, tell PhotoStructure", specifically the “local disk” part. In Unraid, what would NOT be considered a local disk? Even external USB/eSATA drives are treated as local. Can you clarify exactly what you’re trying to get at with this question?

[mrm]

@tkohhh

In Unraid, what would NOT be considered a local disk?

I’ve got the “Unassigned Devices” plug-in installed on my UnRAID box. It’s great: it lets me mount SMB and NFS volumes from my other NASes on to my UnRAID box.

(Docker containers could do the mounting, but then you’d need to run a chef/Ansible/… script to set that up every time you bounced the container.)

[tkohhh]

Gotcha.

For whatever my opinion is worth, I think the vast majority of Unraid users are going to have their photos either on the array, or on a local unassigned device. After all, NAS is the primary function of Unraid. With that in mind, your instructions should probably assume that the user has their photos on local disks, and then provide exception instructions if they do use remote shares.

I think part of my confusion is the terminology. The question asked by the parameter is “Do you want to force a local DB replica?” It’s not clear how that relates to a local vs remote file system. You could think of the question as “Are your files on a remote filesystem?” which would have the same true/false result. But you could also think of the question as “Are your files on a local filesystem?”, which would have an opposite true/false result.

As for my setup, I have never had the PS_FORCE_LOCAL_DB_REPLICA variable set, and as far as I can tell I’ve never had problems related to that (lack of) setting. That of course contributes to my confusion when it’s given such a prominent call-out in this guide.

I’m not sure what the correct answer is, but I at least want to provide an opinion that it’s confusing to me in it’s current state.

edit: a letter

[avdp]

I am probably the reason why @mrm added that in his writeup. I had lots of problems on UNRAID before setting PS_FORCE_LOCAL_DB_REPLICA to false. Never really got to the bottom of ‘why’ - just that all the weird sqlite issues went away after setting to false.

I agree with you that a remote filesystem mount on Unraid, while possible with a plugin, would likely be an edge case. It would make sense for the Unraid docker template to have that setting defaulted to ‘false’.

[bdillahu]

I’m with @tkohhh in that I’ve been running fine without it… I saw a bit of your (@avdp) saga and how it helped, but no clue why

[tkohhh]

This came up in the Discord chat a while ago… this seems like a good place to pick up the discussion.

In order to provide the optimal setup for Unraid, we need to be clear about all of the different paths that Photostructure has. I’m going to attempt to outline that here. @mrm feel free to edit anything that I don’t have quite right.

Library Path (/ps/Library) - This always holds the Photostructure database and image preview files, and also by default holds your auto-organized photos/videos (if that setting is enabled). This path is also always included as a source of images, and will be scanned when sync is run. Default template path: mnt/user/Photos (note: I think this is not a great default since it assumes that the user created a “Photos” user share)

Temp Path (/ps/tmp) - This holds temporary files that Photostructure creates during normal operation. Default template path: /mnt/user/appdata/photostructure/tmp

Config Path (/ps/config) - This holds configuration files like the settings.toml file. Default template path: /mnt/user/appdata/photostructure/config

Logs Path (/ps/logs) - This holds log files generated by Photostructure. Default template path: /mnt/user/appdata/photostructure/logs

Originals Directory (set by PS_ORIGINALS_DIR evnironment variable) - Auto-organization by default saves files to the Library path. You can override this by specifying a different path in the PS_ORIGINALS_DIR environment variable. This is preferable if you want your library database/previews on your SSD cache (which will improve performance), but save your asset files on your Unraid array.

Source Location - Chances are, your asset files already have a home on Unraid. You need to add a path to your Docker setup to allow the Photostructure container to access your files.

[tkohhh]

This post has been moved to it’s own topic here: Tkohhh’s recommended Unraid setup

[Dominik_Wojcik]

I have a question regarding the releases.
Using currenlty: photostructure/server:beta repository
Just found out that in About section I am on Version 2.1.0-alpha.7 with plan Plus.

How I could switch to 2023 one? Should I backup something before making a switch?

[mrm]

Howdy!

The v2023.9 builds are currently available via the :prealpha tag (so change :beta to :prealpha in your unraid template).

Backups are never a bad thing to have — but know that you’ll need to rebuild your library to downgrade back to v2.1.

Please post here or in the PhotoStructure discord if you see anything odd or buggy!

Also, I’m away from my desk for the next couple days, so my responses will be a bit delayed.