PhotoStructure can run on “headless” servers (systems without an addressable graphics display) running Docker hosting Linux x64 images, or directly if running Debian or Ubuntu 18.04 LTS.

Note that other Linux distributions may work, but the installation instructions will be slightly different, and they’ve not been tested on other systems other than Ubuntu 18.04 LTS.

There are two ways to run PhotoStructure on headless systems: either with PhotoStructure for Docker, or with PhotoStructure for Node, which is a standard Node.js application. There are pros and cons to both approaches.

PhotoStructure for Docker


  • PhotoStructure can run within any docker server hosting x64 Linux images. Docker hosts configured for windows images are not supported.
  • Upgrades happen automatically if you use docker-compose.
  • Docker provides a layer of security for your host system.


  • You’ll need to set up docker and docker-compose on your host machine.
  • You’ll need to explicitly export volumes you want to import into PhotoStructure.
  • PhotoStructure won’t have access to volume metadata, so it can’t get the volume UUID of a mount point. If you mount the same volume to a different mount point, PhotoStructure will consider each photo or video it finds to be a new asset file (and possibly double the size of your library database).
  • Due to this issue, libraries created on docker and then opened on the host machine via node or PhotoStructure for Desktop will find all non-library asset files as "missing," due to the lack of the mount point within docker. Asset files copied or found within the library will work (as the paths in the db for these files are stored with relative paths to the library). If you don't expect to open your PhotoStructure library outside of docker, this shouldn't affect you.

Here are the instructions for running PhotoStructure for Docker.

PhotoStructure for Node


  • “Scan all volumes” works automatically. You don’t have to export drives manually from your host machine into your container, like you do with Docker.
  • Volume UUIDs are present, which avoids re-scanning the same drive multiple times


  • Only Ubuntu LTS is officially supported, although any platform that can have the required build toolchain and tools will work.
  • You’ll need to install Node.js, a build toolchain, git, dcraw, jpegtran, sqlite3, and ffmpeg.
  • Upgrades require stopping and restarting PhotoStructure.
  • As with any service, you should set up a role user to run PhotoStructure.

Here are the instructions for running PhotoStructure for Node.


See /advanced-settings for information about PhotoStructures settings files.


  • By default, see ~/.config/PhotoStructure/logs
  • The log directory, verbosity, and formatting are all configurable via ~/.config/PhotoStructure/settings.toml. Search for LOG.
  • You can run photostructure logtail to view all log messages in real time from all services

Library files

$PS_LIBRARY_PATH/.photostructure contains your library database, as well as image and video previews of all the assets in your library.
Opening your model DB in another application (like DB Browser for SQLite) should only be done when PhotoStructure is shut down.

Service architecture

PhotoStructure runs a number of subprocesses to do work. You'll only need to start "main." Everything else is run automatically, when they're needed.

PhotoStructure processes


This process manages web and sync processes, restarting them if they crash or are unresponsive, and restarting sync if the library settings change.


This process hosts the web service, exposing the httpPort to localhost. It also hosts the rpc service for data persistence and orchestration, used by both sync and sync-file instances.


This process scans directories for potential library assets and feeds a cluster of sync-file processes those files, when CPU load is sufficiently low enough.


Expect several of these processes (correlated to the number of CPU cores your system has). These processes do all the work necessary to import files into your library, including building preview images and asking FFmpeg or VLC to transcode videos.

exiftool, jpegtran, dcraw, ffmpeg, vlc, sqlite, powershell, wmic, df, gio, diskutil

These tools will be spawned as needed to

  • Extract file metadata (exiftool)
  • Losslessly transform images (jpegtran)
  • Extract RAW images (dcraw)
  • Transcode videos to be viewable on a browser (ffmpeg or vlc)
  • Compress and validate library databases (sqlite)
  • Extract volume metadata (powershell, wmic, df)
  • Notifications when volumes are mounted or unmounted (gio, diskutil)

Photo by Martijn Baudoin