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 and python3-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 and libheif-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

  1. the directory that holds your PhotoStructure library
  2. ~photostructure/.config/PhotoStructure (the system settings directory)
  3. ~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:

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 #

  1. Install Git for Windows.

  • You want the “64-bit Git for Windows” installer option.

  • Scan the installer for viruses before running.

  • 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!

  1. Install Node.js version 18.

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.

  1. 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.

  1. Install HEIF support (optional)

  2. In a new Git Bash terminal (don’t use cmd 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.

  1. 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 that node, git, and other required tools are installed. It then runs git pull, asks yarn 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 variable PS_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.

Photo of Matthew

Hi! I’m Matthew, the author of PhotoStructure. I’m a dad, amateur photographer, and author of open source, adtech, fintech, and edtech software since the turn of the millennium. He/him. I am building a self-hosted, safe, and fast new home for all your photos and videos.
Your memories deserve PhotoStructure. Try it out for free!