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.
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).
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
python3-devare required to compile PhotoStructure’s native library bindings, used to accelerate image and database operations.
gitis used to download and automatically fetch new PhotoStructure updates.
libheif-examplesenables video and HEIC support.
libjpeg-turbo-progsprovides lossless transformations of JPEG files.
perlis 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)
- The system settings directory default can be changed by setting the
- The scratch directory can be changed by setting the
- 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
Option 2, via
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.
- 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
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.
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
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
Installation for macOS #
PhotoStructure needs the following:
- Xcode’s command line tools,
- Node.js v16,
- 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
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
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
nodeand 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
exit and hitting return.
Install HEIF support (optional)
In a new
Git Bashterminal (don’t use
cmdor 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 npminstalls yarn and makes sure npm is the latest available version.
start.shdownloads 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.
./start.shscript verifies that
git, and other required tools are installed. It then runs
git pull, asks
yarnto install dependencies, and, finally, launches PhotoStructure.
You can use
./start.sh --helpto 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
exposeNetworkWithoutAuthlibrary setting to true, or set the environment variable
PS_EXPOSE_NETWORK_WITHOUT_AUTHto 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 $PIDFILEoption, 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
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.