PhotoStructure for systemd

March 18, 2026

systemd can automatically start PhotoStructure for Node at boot, restart it after crashes, and shut it down gracefully. Most modern Linux distributions (Ubuntu, Fedora, Debian, Raspberry Pi OS) include systemd by default.

This wizard generates a service file tailored to your setup.

Before you begin

Make sure you have:

Completed Steps 1–5 (prerequisites, role user, Node.js, and PhotoStructure downloaded)
Verified that ./server/photostructure works when run manually
The output of id -u and id -g from your terminal

For background on systemd concepts, see Understanding and Administering systemd.

Configure your service file

Fill in the form to generate a photostructure.service unit file.

* indicates required fields.

Service user *

The Linux user that runs PhotoStructure. This should be a dedicated role user, not root. See Step 3.

Group

Defaults to the same as the user. Only change if your photo directories are owned by a different group.

Install directory *

The PhotoStructure installation directory (where you ran git clone).

ExecStart: /home/photostructure/photostructure-for-servers/server/photostructure

How did you install Node.js?

systemd services don't run login scripts (.bashrc, .profile), so Node.js installed via a version manager won't be in $PATH. Select your method so the wizard can set the NODE environment variable.

System package — apt, dnf, or NodeSource nvm — Node Version Manager fnm — Fast Node Manager Volta

Node.js binary path *

Find your path by running which node as your PhotoStructure user. The startup script adds the containing directory to PATH automatically, so npm and npx will also be found.

After upgrading Node.js via your version manager, update this path and run systemctl daemon-reload && systemctl restart photostructure.

Library directory

Where PhotoStructure stores your library database, previews, and organized copies of your photos. Leave empty to set it later via the web UI. See library.

Port

HTTP port for the web UI. Default is 1787.

Log level

See log files.

Allow connections from other devices on my network

PhotoStructure for Node binds to localhost only by default. Check this to set PS_EXPOSE_NETWORK_WITHOUT_AUTH. PhotoStructure has no built-in authentication, so only expose on trusted networks. See remote access.

Advanced options

Environment file

Optional path to a file containing sensitive settings (e.g. PS_LICENSE). One KEY=value per line.

Security hardening

Basic hardening (NoNewPrivileges, PrivateTmp, etc.) is always enabled. Check this box to also enable filesystem restrictions.

Enable strict filesystem protection

ProtectSystem=strict makes the filesystem read-only except for paths listed in ReadWritePaths. ProtectHome=read-only prevents writes to /home except where allowed. Make sure all paths below are correct before enabling.

ReadWritePaths

Space-separated list of directories PhotoStructure needs write access to. Auto-populated from your settings above.

Timeouts and restart

These defaults work well for most systems. Increase TimeoutStartSec if bootstrap is slow (e.g. first run on a Pi).

WatchdogSec

Seconds before a hung service is killed.

TimeoutStartSec

Seconds allowed for startup to finish.

TimeoutStopSec

Seconds allowed for graceful shutdown.

RestartSec

Seconds to wait between restart tries.

Additional environment variables

See PhotoStructure's environment variables for details.

Your photostructure.service

Next steps

Create the library directory (if you set one above):

# Set a library directory above to generate this command

Create the service file by running:
```
sudo systemctl edit photostructure.service --full --force
```
Paste the generated unit file contents, save, and exit.

Reload and enable the service:

sudo systemctl daemon-reload
sudo systemctl enable photostructure.service

Start PhotoStructure:
```
sudo systemctl start photostructure
```
Verify it’s running:
```
systemctl status photostructure
```
Open http://localhost:1787 to complete setup.

Readiness and watchdog

The generated service file uses Type=notify, which means:

Readiness: systemctl start photostructure blocks until the web server is actually listening. You’ll see the status text update in systemctl status.
Watchdog: PhotoStructure sends a keepalive ping every 2 minutes. If the web server becomes unresponsive for 5 minutes (WatchdogSec=300), systemd kills and restarts the service.
Shutdown: When you run systemctl stop, PhotoStructure notifies systemd it’s shutting down and gracefully closes its web and sync processes.

You can see the current status text with:

systemctl status photostructure
# Look for "Status:" line, e.g., "Status: Listening on port 1787"

Control commands

Action	Command
Start	`sudo systemctl start photostructure`
Stop	`sudo systemctl stop photostructure`
Restart	`sudo systemctl restart photostructure`
Status	`systemctl status photostructure`
Logs	`journalctl -u photostructure -f`
Recent logs	`journalctl -u photostructure -n 50`

Upgrading

Just restart the service. The startup script checks for new versions automatically:

sudo systemctl restart photostructure

Troubleshooting

1. Check the journal:

journalctl -u photostructure -n 50

2. Test running manually as the service user:

sudo --login --user photostructure bash
cd ~/photostructure-for-servers
./server/photostructure

If this works but the systemd service doesn’t, the issue is likely environment-related (missing PATH, nvm not sourced).

3. Common issues:

Symptom	Likely Cause	Fix
Fails immediately (Duration: <10ms)	Node.js not found	Select your Node.js install method above
“Permission denied” errors	File permissions	Ensure the service user owns the PhotoStructure directory; check `ReadWritePaths` if you enabled strict security
“Address already in use”	Port conflict	Another process is using port 1787, or PhotoStructure is already running
Start operation timed out	Slow bootstrap	Increase `TimeoutStartSec` or run `server/photostructure --version` manually first
Watchdog timeout (limit 5min)!	Web server hung	Check `journalctl` for errors before the watchdog fired; check memory/disk
“activating” for a long time	Waiting for READY=1	Bootstrap is still running (git pull, npm install) – wait or check logs

4. Port conflicts (EADDRINUSE):

lsof -i :1787        # Find what's using the port
ss -tlnp | grep 1787 # Alternative

# Use a different port by changing the Port field above

5. After making changes to the service file:

sudo systemctl daemon-reload
sudo systemctl restart photostructure

Uninstalling

sudo systemctl disable photostructure
sudo rm /etc/systemd/system/photostructure.service
sudo systemctl daemon-reload

More information

PhotoStructure for Node – full installation instructions for Ubuntu, Fedora, macOS, and Windows
Advanced settings and environment variables
User guide