PhotoStructure for Node
These are instructions for advanced users, wanting to run PhotoStructure for Servers.
Please make sure you’ve read the pros and cons of both approaches before continuing.
Prerequisites #
PhotoStructure for Servers requires:
-
agreement to all terms in the end-user license
-
a 64-bit Intel or AMD CPU. Linux ARM support is experimental, and Apple Silicon is not supported yet.
-
Ubuntu LTS (18.04 or later), Windows 10, or macOS (Mojave or later). (High Sierra support was recently dropped by Homebrew).
-
Node.JS (version 16.15 or later).
Contents #
We’ve got instructions for the following operating systems:
Installation for Ubuntu #
Step 1: Consider hardening your server #
Instructions for “server hardening” are on the forum.
Step 2. Install prerequisite packages #
Open a terminal and run:
sudo apt install -y build-essential python3-dev \
git libjpeg-turbo-progs ffmpeg libheif-examples perl
Notes:
build-essential
andpython3-dev
are required to compile PhotoStructure’s native library bindings, used to accelerate image and database operations.git
is used to download and automatically fetch new PhotoStructure updates.ffmpeg
andlibheif-examples
enables video and HEIC support.libjpeg-turbo-progs
provides lossless transformations of JPEG files.perl
is required by ExifTool which is used to extract metadata from your photos and videos, as well as read and write sidecar files.
Step 3: Create a role user to run PhotoStructure #
Consider creating a role user to run PhotoStructure, as you should do for any service.
sudo adduser --disabled-password photostructure
This role user needs read access to your photos and videos, and write access to
- the directory that holds your PhotoStructure library
~photostructure/.config/PhotoStructure
(the system settings directory)~photostructure/.cache/PhotoStructure
(the scratch directory)
Note:
- The system settings directory default can be changed by setting the
PS_CONFIG_DIR
environment variable. - The scratch directory can be changed by setting the
PS_CACHE_DIR
environment variable. - Read more about advanced settings.
Step 4: Install Node.js #
There are two ways to install the current version of Node.js. There are pros and cons to each:
Option 1, via your package manager: #
Install Node.js via NodeSource packages:
curl -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -;
sudo apt install nodejs
This option means that your version of Node will be upgraded along with your other system packages, which is good for security.
If you have any other software on your server that needs a different version of Node.js you may want to use nvm
instead.
Option 2, via nvm
: #
Node Version Manager, or nvm
, manages one or more versions of Node.js, per user.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
and then restart your shell, and run
nvm install 16 --latest-npm
Security updates to Node.js will not be applied automatically. When a new version is available, you need to run nvm install 16 --reinstall-packages-from=16 --latest-npm
.
Notes #
- PhotoStructure requires Node.js version 16 or later.
- Consider curling (any!) setup script to a file and reviewing the file before executing as root.
- You will have performance problems if you use the snap version of Node.js.
Step 5: Download and start PhotoStructure #
This assumes you’re going to install PhotoStructure into your new role user’s
home directory, ~photostructure
.
sudo --login --user photostructure bash
cd ~photostructure
git clone https://github.com/photostructure/photostructure-for-servers.git
cd photostructure-for-servers
./start.sh
Jump to the Start PhotoStructure section for more information.
Step 6: Set up a systemd service (optional) #
You can use systemd to make PhotoStructure start up on boot and gracefully end when your system shuts down.
Configure the service #
Start by running sudo systemctl edit photostructure.service --full --force
and paste
the following content into your editor.
Note that the following assumes you’ve set up a photostructure
role user and installed into the directory from the prior section.
Update User
, Group
, and ExecStart
according to your own setup.
[Unit]
Description=PhotoStructure for Servers
Documentation=https://photostructure.com/servers/
# PhotoStructure binds to either 0.0.0.0 or 127.0.0.1, so we don't need to
# wait for network-online.target. See https://systemd.io/NETWORK_ONLINE/
Wants=network.target
After=network.target
[Service]
User=photostructure
Group=photostructure
ExecStart=/home/photostructure/photostructure-for-servers/start.sh --expose
Type=simple
Restart=on-failure
TimeoutSec=2min
# Remove this line if you have an old version of systemd that doesn't support PrivateTmp:
PrivateTmp=true
[Install]
WantedBy=default.target
Control the service #
Control the PhotoStructure service just as you would any other systemd
service.
-
To start the PhotoStructure service:
sudo systemctl start photostructure
-
To stop the PhotoStructure service:
sudo systemctl stop photostructure
-
To view the current status of the service:
sudo systemctl status photostructure
Enable the service #
Once you’re satisfied that the service is running correctly, enable the service to start on boot:
sudo systemctl enable photostructure.service
Uninstalling the service #
- To disable start on reboot, run
sudo systemctl disable photostructure
. - To uninstall, remove the
/etc/systemd/system/photostructure.service
file.
Installation for macOS #
PhotoStructure needs the following:
- Xcode’s command line tools,
- Node.js v16,
- ffmpeg,
- jpeg-turbo,
- Python 3.9, and
- Rosetta 2 on Apple Silicon (M1) Macs
You’re free to install these by yourself, but homebrew makes this much easier.
Step 1. Install Xcode command line tools #
Open Terminal.app and run this:
xcode-select --install
sudo xcode-select --reset
Note that xcode-select
may grump about being already installed: that’s OK.
Step 2. Install homebrew #
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
If you’re concerned about the content of that install script, run this instead:
curl --fail --silent --show-error --location https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh --output install.sh
# at this point open install.sh in an editor and verify it does reasonable things
/bin/bash install.sh
Step 3. Install PhotoStructure’s dependencies #
In a terminal, run
brew upgrade
# ffmpeg has a TON of dependencies. This will take a while:
brew install ffmpeg jpeg-turbo
# running this will emit some post-instructions:
brew install [email protected]
# If you've customized your shell or paths, use the instructions
# from brew instead of the following:
echo 'export PATH="/opt/homebrew/opt/[email protected]/bin:$PATH"' >> ~/.zshrc
echo 'export LDFLAGS="-L/opt/homebrew/opt/[email protected]/lib"' >> ~/.zshrc
echo 'export CPPFLAGS="-I/opt/homebrew/opt/[email protected]/include"' >> ~/.zshrc
Then restart your terminal to pick up your changes to ~/.zshrc
.
PhotoStructure requires Node v16. Node v18 has a compilation issues on Apple Silicon Macs.
ffmpeg
supports an astounding number of different video formats. Because of this, it has a ton of dependencies, so expect installation to take a while.
Step 4. Download PhotoStructure #
In a terminal, run
cd ~
git clone https://github.com/photostructure/photostructure-for-servers.git
cd photostructure-for-servers
./start.sh
Jump to the Start PhotoStructure section for more information.
Installation for Windows 10/11 #
- Install Git for Windows.
-
You want the “64-bit Git for Windows” installer option.
-
The git installer asks a lot of questions: PhotoStructure will work fine if you accept all the defaults. Hop into Discord if you have questions, though!
-
Install Node.js version 18.
-
Keep “Add to PATH” selected.
-
On the last screen, select “Automatically install the necessary tools.”:

The installation will take a while, as the Node.js installer will install
Chocolatey, and then ask choco
to install the tools
necessary to build native modules. PhotoStructure uses several of these modules,
so this step cannot be skipped.
- After installing
node
and the build tools finish installing, open a new Administrator PowerShell, and run:
choco install ffmpeg jpegtran
Wait for the installations to finish, and then close the PowerShell window
by typing exit
and hitting return.
-
Install HEIF support (optional)
-
In a new
Git Bash
terminal (don’t usecmd
or PowerShell!), run these commands:
npm install --global yarn npm
cd ~ # (or whatever directory you want to install PhotoStructure into)
git clone https://github.com/photostructure/photostructure-for-servers.git
cd photostructure-for-servers
./start.sh
-
npm install --global yarn npm
installs yarn and makes sure npm is the latest available version. -
start.sh
downloads and installs some additional software (like exiftool-vendored).This can take a while, but it only happens after PhotoStructure or Node.js is upgraded. Subsequent restarts should be quick.
- If you want PhotoStructure to run at startup, follow these instructions.
Starting PhotoStructure #
cd ~photostructure/photostructure-for-servers # or wherever you cloned the repo
./start.sh
The process should print a localhost URL for you to open with a browser. Current versions of Chrome, Firefox, and Safari on both desktop and mobile are supported.
Notes:
-
The
./start.sh
script verifies thatnode
,git
, and other required tools are installed. It then runsgit pull
, asksyarn
to install dependencies, and, finally, launches PhotoStructure. -
You can use
./start.sh --help
to see more detailed usage information. -
The first time you run
start.sh
, it will download and compile dependencies, which will take a moment, and then launch PhotoStructure. Subsequent starts will be much faster, unless there is a new release or your version of node is upgraded. Recompilation happens automatically. -
PhotoStructure currently binds to localhost only by default, so if you want to access it elsewhere, you need to either set the
exposeNetworkWithoutAuth
library setting to true, or set the environment variablePS_EXPOSE_NETWORK_WITHOUT_AUTH
to 1. Note that as of version 0.8, there is no authentication functionality within PhotoStructure. This feature will be added in a subsequent release. -
If you use the
--pidfile $PIDFILE
option, the process will daemonize and return you to your shell prompt.
Shutting down PhotoStructure #
It’s easiest to shut down PhotoStructure via the navigation menu (the “hamburger” icon in the upper right corner of the UI).
If you’re running start.sh
in the foreground in a terminal, just hit ctrl-c. The photostructure main
process will gracefully shut down when sent a SIGINT
signal.
If you’ve daemonized it with a --pidfile
, run something like ./photostructure --stop --pidfile /var/run/photostructure.pid
Why is it taking so long to shut down? #
PhotoStructure may take upwards of a minute to shut down gracefully, depending on the size of your library and the speed of the disk your library is hosted on, as closing the library database requires copying your library database back to your library when it’s hosted on a remote filesystem.
Upgrading PhotoStructure #
If you’re using systemd
, just run sudo systemctl restart photostructure
to pick up the new release.
Otherwise, shut down and restart PhotoStructure: ./start.sh
checks for new versions every time it starts.
Switching between alpha, beta, and stable release channels #
The “release channel” you’re using is based on the git branch
you’ve checked out.
If, for any reason, you want to switch to the “stable” release, open a terminal and run
sudo su - photostructure
cd ~/photostructure-for-servers
git fetch
git stash -u
git checkout main
Read this forum post to learn more about different release channels (alpha, beta, and stable).
Raspberry Pi installation instructions have been moved here.