--- title: PhotoStructure for systemd url: https://photostructure.com/server/systemd/ description: Interactive systemd service file generator for PhotoStructure for Node date: 2026-03-18 keywords: Node.js, installation, Linux, settings, environment-variables, troubleshooting --- [systemd](https://systemd.io/) can automatically start [PhotoStructure for Node](/server/photostructure-for-node/) at boot, restart it after crashes, and shut it down gracefully. Most modern [Linux](/server/photostructure-for-node/#ubuntu-install) 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](/server/photostructure-for-node/#ubuntu-install) (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](https://docs.fedoraproject.org/en-US/quick-docs/understanding-and-administering-systemd/index.html). ## Configure your service file Fill in the form to generate a `photostructure.service` unit file. \* indicates required fields.

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

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

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

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

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.

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.

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.

HTTP port for the web UI. Default is 1787.

See log files.

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

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

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

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.

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

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

Seconds before a hung service is killed.

Seconds allowed for startup to finish.

Seconds allowed for graceful shutdown.

Seconds to wait between restart tries.

See PhotoStructure's environment variables for details.

Your photostructure.service

## Next steps 1. Create the library directory (if you set one above): 
# Set a library directory above to generate this command
2. Create the service file by running: ```sh sudo systemctl edit photostructure.service --full --force ``` Paste the generated unit file contents, save, and exit. 3. Reload and enable the service: ```sh sudo systemctl daemon-reload sudo systemctl enable photostructure.service ``` 4. Start PhotoStructure: ```sh sudo systemctl start photostructure ``` 5. Verify it's running: ```sh 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: ```sh 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: ```sh sudo systemctl restart photostructure ``` ## Troubleshooting **1. Check the journal:** ```sh journalctl -u photostructure -n 50 ``` **2. Test running manually as the service user:** ```sh 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`):** ```sh 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:** ```sh sudo systemctl daemon-reload sudo systemctl restart photostructure ``` ## Uninstalling ```sh sudo systemctl disable photostructure sudo rm /etc/systemd/system/photostructure.service sudo systemctl daemon-reload ``` ## More information - [PhotoStructure for Node](/server/photostructure-for-node/) -- full installation instructions for Ubuntu, Fedora, macOS, and Windows - [Advanced settings](/getting-started/advanced-settings/) and [environment variables](/faq/environment-variables/) - [User guide](/getting-started/user-guide/)