Server setup

The Fotoloka server is the half that holds the photos. It runs on a computer you already own, quietly in the background, and starts again on its own at every login or boot. This page takes you from a downloaded zip to a working library.

• What you need
• Download
• Installing on macOS
• Installing on Windows
• Installing on Linux and the Raspberry Pi
• Stop the machine going to sleep
• Configuration
• Using an external hard drive
• Backing up, and recovering onto a new computer
• Watching albums on a Smart TV
• If something is not working

What you need

• A computer that stays on when the family is home — a Mac, a Windows PC, a Linux box, or a Raspberry Pi. A Pi with a USB drive makes a silent, cheap server that costs pennies a year to run.
• Java 21 or newer on that machine. There is no bundled runtime, so install it first:

  macOS	brew install --cask temurin@21, or a .pkg from adoptium.net
  Windows	The Temurin 21 .msi from adoptium.net
  Raspberry Pi / Debian	sudo apt update && sudo apt install -y default-jre

  Check it with java -version. The installers stop with a clear message if Java is missing, so you can install it and run them again.
• Everyone on the same Wi-Fi. Fotoloka is a home-network service; there is nothing to open to the internet, and you should not.

Download

Inside the zip:

fotoloka-server-3.0.1/
  photo-backup-server-all.jar      the server itself
  photobackup.properties.example   every setting, documented
  README.txt                       a short version of this page
  macos/     install.sh  uninstall.sh  and the launchd agents
  windows/   install.bat uninstall.bat run-server.bat
  linux/     install.sh  uninstall.sh  fotoloka.service

Verify the download if you like — shasum -a 256 fotoloka-server-3.0.1.zip on macOS or Linux, certutil -hashfile fotoloka-server-3.0.1.zip SHA256 on Windows — and compare it with the checksum above.

Installing on macOS

Unpack the zip, open Terminal in the unpacked folder, and run:

chmod +x macos/install.sh
./macos/install.sh

To keep the library on an external drive instead, pass the folder:

./macos/install.sh /Volumes/MyExternalDrive/PhotoBackup

The installer:

• copies the server to ~/Applications/FamilyPhotoBackup/;
• creates photobackup.properties there, readable only by your account;
• registers a launchd agent at ~/Library/LaunchAgents/com.qspapps.photobackup.plist so the server starts at every login;
• starts it straight away.

Then check it: open http://localhost:8080/ on that Mac.

One more thing before you walk away: a sleeping Mac answers nothing. See Stop the machine going to sleep — it is the difference between a server that works and one that seems to work.

Stopping, starting and uninstalling

launchctl unload ~/Library/LaunchAgents/com.qspapps.photobackup.plist   # stop
launchctl load   ~/Library/LaunchAgents/com.qspapps.photobackup.plist   # start

To remove it completely:

./macos/uninstall.sh

That stops the service, deregisters it and deletes the program. Your photo library is left exactly where it is — no uninstaller here deletes a photo.

Installing on Windows

Extract the zip, then double-click windows\install.bat, or from a Command Prompt:

windows\install.bat

To keep the library on an external drive:

windows\install.bat D:\PhotoBackup

The installer:

• copies the server to %APPDATA%\FamilyPhotoBackup\;
• creates photobackup.properties there;
• puts FamilyPhotoBackup.bat in your Startup folder, so the server launches at every login;
• starts it straight away.

Windows Firewall will ask whether to allow Java on your network the first time. Allow it on Private networks. If you say no, no phone on your Wi-Fi will find the server.

And before you walk away: a sleeping PC answers nothing, and its Wi-Fi adapter will power itself down even when it does not. See Stop the machine going to sleep.

Stopping, starting and uninstalling

Close the FamilyPhotoBackup Server window to stop it; run FamilyPhotoBackup.bat from your Startup folder to start it again. To remove it:

windows\uninstall.bat

Installing on Linux and the Raspberry Pi

A Raspberry Pi with an external USB drive is an excellent Fotoloka server: silent, always on, and cheap to run. Mount the drive somewhere permanent first — give it an entry in /etc/fstab so it comes back after a reboot — then:

chmod +x linux/install.sh
sudo ./linux/install.sh /mnt/photobackup

Leave the folder off to use ~/Pictures/FamilyPhotoBackup instead.

The installer:

• copies the server to /opt/fotoloka/;
• writes a systemd unit at /etc/systemd/system/fotoloka.service, enabled at boot and restarted automatically if it ever stops;
• runs the service as the account that invoked sudo, not as root, so the library stays owned by a real user;
• starts it straight away.

systemctl status fotoloka      # is it running?
journalctl -u fotoloka -f      # what is it saying?
sudo systemctl restart fotoloka
sudo ./linux/uninstall.sh      # remove it; the photos stay

The Pi advertises itself over mDNS across your router just as a laptop does, so the Android app finds it with nothing to configure.

Stop the machine going to sleep

This is the single most common reason a Fotoloka server seems unreliable. A laptop that has gone to sleep answers nothing: it stops advertising itself on the network, the dot in the app turns grey, and backups stall until somebody touches the keyboard. It looks exactly like a broken server, and it is a sleeping one.

The giveaway is the pattern. If any of this sounds familiar, read on:

• It works while you are sitting at the laptop, and is unreachable an hour later.
• Backups only ever seem to run when you happen to open the lid.
• Photos taken during the day all arrive at once in the evening.
• The app finds the server the moment you wake the machine, every time.

The fix is the same everywhere — tell the machine not to sleep while it is on mains power. Below is how, per platform. Leave the sleep-on-battery settings alone: a server unplugged on a shelf is a flat battery, and nothing is backing up to it anyway.

macOS

Open System Settings, then:

• Battery on a laptop (Energy Saver on a Mac mini or an iMac) → Options, and turn on Prevent automatic sleeping on power adapter when the display is off. On a desktop Mac this is simply Prevent automatic sleeping when the display is off.
• Turn on Wake for network access in the same place. Treat it as a helper rather than the fix: it depends on a Bonjour sleep proxy being present on your network, and it is not dependable enough to rely on by itself.
• If your library is on an external USB drive, turn off Put hard disks to sleep when possible. A spun-down disk is not a failure — the first thumbnail is just slow — but there is no reason to make the family wait.

The same settings from a terminal, which is handy on a Mac you administer over SSH:

sudo pmset -c sleep 0        # never sleep on mains power
sudo pmset -c disksleep 0    # never spin the disks down on mains power
sudo pmset -c womp 1         # wake for network access
pmset -g custom              # check what you just set

Closing the lid sleeps a MacBook regardless of any of this. If the Mac is going to live shut in a drawer, you have three choices: leave the lid open; run it in clamshell mode, which needs mains power and an external display attached; or lift the lid-close rule outright with sudo pmset -b disablesleep 1. That last one keeps the machine awake on battery too, so use it only on a Mac that is permanently plugged in — sudo pmset -b disablesleep 0 puts it back.

To see what is putting the Mac to sleep, or holding it awake: pmset -g assertions, and pmset -g log | grep -e "Sleep " -e "Wake " for the history.

Windows

Three separate settings matter, and missing any one of them leaves the server dropping out.

1. Sleep. Settings → System → Power & battery (Windows 11) or Power & sleep (Windows 10). Under Screen and sleep, set When plugged in, put my device to sleep after to Never. Letting the screen switch off is fine and saves more power than it sounds like.
2. Hibernation. Sleep and hibernate are different timers and Windows will happily hibernate a machine you told not to sleep. Control Panel → Power Options → Change plan settings → Change advanced power settings → Sleep → Hibernate after → 0 (never) on Plugged in.
3. The Wi-Fi adapter. This one catches people out, because the PC stays awake and the server still becomes unreachable. Device Manager → Network adapters → your Wi-Fi adapter → Properties → Power Management → untick Allow the computer to turn off this device to save power.

And, on a laptop, Control Panel → Power Options → Choose what closing the lid does → When plugged in → Do nothing.

The first two from an Administrator Command Prompt, if you prefer:

powercfg /change standby-timeout-ac 0     :: never sleep on mains
powercfg /change hibernate-timeout-ac 0   :: never hibernate on mains
powercfg /change disk-timeout-ac 0        :: never spin the disks down
powercfg /requests                        :: what is holding it awake right now
powercfg /lastwake                        :: what woke it last

Linux and the Raspberry Pi

A Raspberry Pi never sleeps, which is a good part of why it makes the best Fotoloka server: plug it in and it is simply always there. There is nothing to configure.

One thing on a Pi is worth turning off, though — Wi-Fi power saving, which makes discovery and the first request after an idle spell flaky:

sudo iw dev wlan0 set power_save off        # right now
# and to survive a reboot, on a NetworkManager system:
sudo nmcli connection modify <your-wifi> wifi.powersave 2

Better still, give the Pi a wired connection. Ethernet has no power saving to fight.

On a Linux laptop acting as the server, stop it suspending:

sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target

And stop the lid from triggering it — in /etc/systemd/logind.conf:

HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore

Then sudo systemctl restart systemd-logind. On a GNOME desktop the session has its own idle timer on top of all this, which you turn off with:

gsettings set org.gnome.settings-daemon.plugins.power sleep-inactive-ac-type 'nothing'

Checking it actually worked

Do not test this by walking away for two minutes. Leave the machine alone for an hour — untouched, lid in whatever position it will normally be — and then, from a different device on the Wi-Fi, open http://<server-ip>:8080/. If it answers straight away, you are done. If it answers only after a pause, or not at all until you touch the laptop, something is still sending it to sleep.

The server's own log is the other witness: a clean night shows continuous activity, and a sleeping machine leaves an obvious hole in it.

Is leaving it on a problem?

A modern laptop sitting idle with the screen off draws a handful of watts — a few pounds or dollars a year. Letting the display sleep costs you nothing and saves most of it; it is only system sleep that has to go.

If the idea of leaving a laptop on all the time still does not appeal, this is the argument for a Raspberry Pi: about 3 watts, silent, no lid, no battery, no sleep settings to get wrong, and it comes straight back after a power cut.

Configuration

Every setting lives in one file, photobackup.properties, next to the installed server. Edit it, restart, done — there is nothing to export on a command line. The installer prints its exact path when it finishes.

It arrives fully commented, with every option explained in place. Uncomment what you need:

# Where your photos are kept. Point it at an external drive to keep them off the laptop.
storage.root = /Volumes/FamilyDrive/PhotoLibrary

# A password every client must present. Leave it out for no password.
server.password = choose-something-memorable

# Serve albums to a Smart TV browser. Read "Watching albums on a Smart TV" below first.
tv.enabled = true

Restart the server after editing — the file is read once, at startup:

Checking it took effect

The startup log says which file it read and what it decided:

[Config] Loaded /Users/you/Applications/FamilyPhotoBackup/photobackup.properties
[Config] storage.root=/Volumes/FamilyDrive/PhotoLibrary (configured), server.password=set, tv.enabled=true

If a change does not seem to have applied, look there first. Visiting http://<server-ip>:8080/ also shows the storage path and whether the TV page is on.

If you set a password

Keep the file to yourself — it is now a secret:

chmod 600 ~/Applications/FamilyPhotoBackup/photobackup.properties

The installers do this for you. The server warns at startup if it holds a password and other accounts on the machine can read it.

Environment variables

PHOTO_BACKUP_ROOT, PHOTO_BACKUP_PASSWORD and PHOTO_BACKUP_TV are honoured too, and take priority over the file, so an older setup that exports them keeps working unchanged. That also makes one-off runs easy:

PHOTO_BACKUP_TV=true java -jar photo-backup-server-all.jar

If you want the file to be in charge, remove those variables from wherever you set them. PHOTO_BACKUP_CONFIG=/path/to/file.properties points the server at a config file anywhere you like.

Using an external hard drive

A laptop disk fills up quickly with a decade of photos. Point Fotoloka at an external USB drive and the photo files, the cached thumbnails and the index database all live there instead — which makes the library portable and trivially easy to back up.

Pass the folder to the installer:

./macos/install.sh /Volumes/MyExternalDrive/PhotoBackup      # macOS
windows\install.bat D:\PhotoBackup                           # Windows
sudo ./linux/install.sh /mnt/photobackup                     # Linux / Pi

That writes storage.root into your settings file. To move the library later, edit that one line and restart — you do not have to reinstall. On macOS the launch agent additionally watches the path, so the server shuts down cleanly if you unplug the drive.

Backing up, and recovering onto a new computer

Backing up

Because the database and the photo files sit in the same folder, cloning the whole vault to a second drive is one command. Nothing needs to be shut down first — SQLite copies safely while the server is running.

# macOS / Linux
rsync -avz --delete /Volumes/MyExternalDrive/PhotoBackup/ /Volumes/MySecondaryBackupDrive/PhotoBackup/

# Windows
robocopy D:\PhotoBackup E:\PhotoBackup /MIR

Recovering onto a new computer

If the laptop dies:

1. Connect the external drive to the new machine.
2. Install Java 21, then download and unpack this zip.
3. Run the installer, passing the drive folder — for example ./macos/install.sh /Volumes/MyExternalDrive/PhotoBackup.

The server finds the existing database, keeps every family member's settings, and carries on serving the same photos and albums. The phones reconnect on their own.

Watching albums on a Smart TV

The server can serve a page any television's browser can open — Samsung, LG, Android TV, a Fire Stick's browser, or a laptop plugged into the HDMI port. It is off by default. Turn it on in your settings file and restart:

tv.enabled = true

Then open http://<server-ip>:8080/tv/ on the television, and bookmark it as the browser's home page. How to drive it with the remote is in the user guide.

What this exposes — please read

This page is not password protected. That is deliberate: a TV remote is a miserable way to type a password. It is bounded instead:

• Albums only. The TV shows the albums your family has created and nothing else — no browsing the library by date, person, tag or place. A photo that is not in an album cannot be reached from the TV at all, even by someone who knows its filename. If you want something on the television, put it in an album; if you do not, leave it out of one.
• Read-only. Nothing on the TV page can delete, change or upload anything.
• Off unless you turn it on, and turning it on does not weaken the app's API — that stays behind server.password if you have set one.

The practical effect: while it is enabled, anyone on your home Wi-Fi can view your shared albums without a password. On a household network that is the whole point. If guests share your Wi-Fi and that concerns you, leave it off, or put the TV on a guest-isolated network.

If something is not working

The server works, then stops, then works again when you touch the laptop

The machine is going to sleep. This is the most common complaint about Fotoloka and it is not the software — see Stop the machine going to sleep.

The app cannot find the server

First rule out sleep, which accounts for most of these. Then check both devices are on the same Wi-Fi — a phone on 5 GHz and a laptop on a guest network will not see each other. On Windows, confirm Java is allowed through the firewall on Private networks. Then open http://<server-ip>:8080/ in a browser on another machine: if that answers, the server is fine and the problem is discovery, so tap the status dot in the app to retry.

A setting seems to be ignored

Restart the server — the file is read once, at startup. Then read the [Config] lines in the log, which name the file that was loaded. An environment variable set somewhere else overrides the file.

The server will not start

Read the log. The usual causes are no Java on the machine, or something else already listening on port 8080 — often a second copy of Fotoloka.

On macOS, it works in Terminal but not at login

The launch agent calls /usr/bin/java, which resolves to a JDK registered with the system. A Java installed only on your shell's PATH is invisible to it. Install a system JDK — a .pkg, or brew install --cask temurin@21 — and run the installer again.

A video will not play in the browser

That is your browser, not Fotoloka. The server streams your file exactly as recorded and never re-encodes it, so a clip plays only if the browser can decode it. Recent iPhones and many Android phones record HEVC (H.265), which desktop Chrome and Firefox generally will not play; Safari usually will, and the Android app always will. Set your camera to its "most compatible" / H.264 option if you want playback everywhere.