PhotoBlad on a Mac

Shared privately for now. The Mac package is made and tried, and the owner hands it to the people they choose through a private download page on GitHub. It isn’t published for everyone yet. The step-by-step guide that comes inside the download, README.md, is the exact one for the version you have; this page says what the package is and what to expect.

The package holds PhotoBlad’s two programs, the Server (the web page and everything you see) and the Indexer (which reads your folders and keeps the backups), and the photoblad command that installs and looks after them. Nothing else needs to be installed first. Every program in it is signed, and Apple’s notary service has checked the download.

PhotoBlad runs as part of your Mac account. It starts when you log in, starts again by itself if it crashes, and keeps running while the Mac is awake. Its web page is at http://localhost:5180 on that Mac.

What you need

• The download for your Mac’s processor. An Apple silicon Mac (M1 or later) needs the file ending macos-arm64.tar.gz, and macOS 14 Sonoma or newer. An Intel Mac needs macos-x64.tar.gz and macOS 15 Sequoia or newer. On an Intel Mac PhotoBlad’s own AI models (search by what’s in a photo, faces, removing an object) don’t run, because the library they use has no version for it. Everything else works, and describing photos with Ollama does too.
• About 300 MB for the program, and room for the photos and videos people back up.
• The Mac switched on, awake, and you logged in whenever someone wants to use PhotoBlad (see Sleep).

Install it

Download the .tar.gz and the .sha256 file beside it, check the download, unpack it by double-clicking it, and run its photoblad install in Terminal:

cd ~/Downloads
shasum -a 256 -c photoblad-server-<version>-macos-arm64.tar.gz.sha256
~/Downloads/photoblad-server-<version>-macos-arm64/photoblad install

The check must say OK. install checks every file, every program’s signature and, by asking Apple, the notarization, so the Mac needs the internet for this step. Then it copies PhotoBlad to ~/Applications/PhotoBlad, opens the menu-bar icon and starts PhotoBlad, and prints a one-time setup code. Open http://localhost:5180, enter the code, and choose your name, a username and a password of at least 12 characters: you are the owner.

If port 5180 or 5181 is taken, install says so, and photoblad install --port 5190 --indexer-port 5191 uses others. --data <folder> and --storage <folder> put PhotoBlad’s data and backups elsewhere, the first time. macOS may show a Background Items Added notice for PhotoBlad’s programs: leave them allowed.

Videos need FFmpeg: choose Install FFmpeg for me while you set up, or later in Settings → Updates → Add-ons.

The photoblad command

From then on the command is ~/Applications/PhotoBlad/photoblad (add alias photoblad=~/Applications/PhotoBlad/photoblad to ~/.zshrc to type less):

The menu-bar icon

The icon, the leaf on a tile, shows whether PhotoBlad is running, starting, stopped, or not answering because it ended with an error, and what needs you as the owner: the notices Settings → Health shows, and a missed security release. Its menu opens PhotoBlad or Settings → Health, copies PhotoBlad’s address, restarts or stops PhotoBlad (it asks first), and opens the logs. On a first start it shows the setup code.

• Tell Me When Something Needs Me sends one notification for each new thing that needs you. It’s on to start with.
• Open at Login is on to start with. Hide Menu Icon takes the icon away and PhotoBlad keeps running; open PhotoBlad from Spotlight to bring it back.
• It asks only the PhotoBlad on this Mac, with a key in PhotoBlad’s data folder that only your Mac account can read. It never signs in and keeps no password.

Letting PhotoBlad read your photos

macOS keeps programs out of Desktop, Documents and Downloads, the Photos library, and external and network drives until you allow them, and it answers as if the folder weren’t there. photoblad allow-folders opens the right page of System Settings and shows the two programs to allow, PhotoBlad.Indexer and PhotoBlad.Server: add each under Privacy & Security → Full Disk Access, then photoblad restart. The same goes for a storage location on an external drive. The programs always live in ~/Applications/PhotoBlad/current, so the permission stays after an update.

If your photos are in the Photos app, scan the library itself, ~/Pictures/Photos Library.photoslibrary.

Phones and other computers: Tailscale

As installed, PhotoBlad answers only on this Mac. Phones, the PhotoBlad app (which connects only to HTTPS addresses) and other computers can reach it through Tailscale, a private network of your own devices: you turn on HTTPS for your tailnet once in its admin console, run tailscale serve --bg 5180 on the Mac, and add https://<this Mac's name>.<your tailnet>.ts.net in Settings → Public address (or run photoblad address add https://<this Mac's name>.<your tailnet>.ts.net in Terminal). Nothing is opened to the internet. The package’s guide has each step, and Self-hosting explains Tailscale and Caddy.

At home, straight over the Wi-Fi. From the next release, Settings → Public address has an On your home network card: pick this Mac’s address on your network from its suggestions and choose Turn it on (or run photoblad address local http://<this Mac's address>:5180). A phone whose owner turns on Prefer local network on Wi-Fi in its Account sheet then uses that address at home, with no tunnel and at full speed, after checking that the server answering is this one, and its https address everywhere else. It needs an https address first, and give the Mac a fixed address on your network in the router, so the address doesn’t change.

Public domain on the internet: Caddy

If you want family members (and, from the next release, connected PhotoBlad servers) to reach your Mac at your own domain name (such as photos.example.com) without installing Tailscale on their phones, you can set it up straight from Settings → Public address in the web app (or from Terminal):

1. Point your domain and router at this Mac:
   • Give this Mac a static LAN IP (DHCP reservation) in your router’s settings so its local address (192.168.x.x) never changes after a reboot.
   • Create a DNS A record for your domain pointing to your home router’s public IPv4 address. Add an AAAA record only if this Mac has a public IPv6 address and your router forwards IPv6 to it (a broken AAAA record will make Let’s Encrypt validation fail).
   • Forward ports on your router to this Mac’s LAN IP: TCP port 80 (HTTP, for Let’s Encrypt validation and HTTP-to-HTTPS redirect), TCP port 443 (HTTPS), and UDP port 443 (HTTP/3 QUIC).
2. Turn Caddy on in Settings → Public address (or Terminal):
   • In the web app: Open Settings → Public address. If Caddy isn’t installed yet, click Install Caddy for me (which downloads the pinned Caddy 2.11.4 build for your Mac, verifies its SHA-256 hash, and installs it into ~/.photoblad/dependencies/caddy/) or install it with brew install caddy. Enter your domain (photos.example.com) and optional Let’s Encrypt email, adjust HTTP port / HTTPS port if your router forwards a custom public HTTPS port (such as external 8443), click Check DNS & ports to verify your A/AAAA records and local port availability, and click Turn on Caddy & HTTPS. You can also test with Let’s Encrypt’s staging CA first, switch from Tailscale to Caddy (or keep both addresses active at once), remove old addresses, and change PhotoBlad’s local service ports (5180/5181) on the same page.
   • Or from Terminal:

     # Optional: test your DNS and router port-forwarding with Let's Encrypt's staging CA first:
     ~/Applications/PhotoBlad/photoblad caddy on photos.example.com --email you@example.com --staging
     
     # Switch to a trusted production Let's Encrypt certificate:
     ~/Applications/PhotoBlad/photoblad caddy on photos.example.com --email you@example.com
     

   Turning Caddy on writes ~/.photoblad/caddy/Caddyfile (with a 16 GiB upload body limit, streaming flush_interval -1, Strict-Transport-Security, redacted access logs in ~/.photoblad/logs/caddy.log, and a maintenance page while PhotoBlad restarts), adds https://photos.example.com to PhotoBlad’s public addresses, starts Caddy as a launchd agent so it runs at login, and restarts PhotoBlad. Caddy renews its 90-day Let’s Encrypt certificate automatically in the background about 30 days before expiry.
3. At home on Wi-Fi (hairpin NAT or split-horizon DNS): If https://photos.example.com works on cellular data but fails on your home Wi-Fi, your router isn’t looping public-IP traffic back inside (hairpin NAT / NAT loopback). Either turn on NAT loopback in your router’s settings, or add a local DNS record (split-horizon DNS) in your router, Pi-hole, or AdGuard Home that resolves photos.example.com directly to this Mac’s LAN IP (192.168.x.x). Because the hostname still matches photos.example.com, Caddy’s Let’s Encrypt certificate stays valid and home Wi-Fi uploads stay directly on your local network at full LAN speed.
4. Checking or stopping Caddy: Use Settings → Public address (Turn off Caddy), or run:

   ~/Applications/PhotoBlad/photoblad caddy status
   ~/Applications/PhotoBlad/photoblad caddy off
   

Updating

When the owner publishes a new version, Settings → Updates says so and offers Update to PhotoBlad <version> and restart (plus Install from a file… if you downloaded the .tar.gz in your browser). Clicking it downloads or checks the .tar.gz, verifies its SHA-256 against the signed feed, unpacks it, checks every program’s signature and Apple’s notarization, copies the new version beside the old one, stops PhotoBlad, switches ~/Applications/PhotoBlad/current to the new version and starts it again, copying the database to ~/.photoblad/backups/ before it changes anything. You can also run ~/Applications/PhotoBlad/photoblad update in Terminal, or follow the manual commands under Show manual steps. The version you had stays beside it for going back, and the package’s guide says how. Nothing updates itself without your click.

Sleep

PhotoBlad works while the Mac is awake and you are logged in. To keep a desktop Mac awake with its screen off, turn on Prevent automatic sleeping when the display is off in System Settings → Energy. What a phone backs up while the Mac sleeps waits on the phone until the Mac is awake again, and the nightly maintenance runs soon after it wakes.

Keeping your photos safe

PhotoBlad never changes the folders you scan. What people back up lives in ~/PhotoBlad (and any storage location you add), and PhotoBlad’s own data, with everyone’s accounts, in ~/.photoblad. Keep a second copy of both, for example with Time Machine. PhotoBlad also copies its database every night, into the storage folder.

Moving PhotoBlad’s data

PhotoBlad’s own data (the database, its logs, the keys and the settings) moves by a command and never from a button, so that nothing is half moved while PhotoBlad runs:

~/Applications/PhotoBlad/photoblad move-data /Volumes/Drive/PhotoBlad-data

It checks everything before it stops anything: the folder must be new or empty, apart from your library folders and storage, on a disk with room for the data and 1 GB more. Then it stops PhotoBlad, copies the data keeping every permission, checks the copy’s database, and starts PhotoBlad from there. If the copy or its check fails, the copy is deleted and PhotoBlad starts again from the old folder. The old folder stays until you run photoblad move-data --forget-old. Keep the data on a drive that stays connected: while it is away, PhotoBlad can’t run. The caches and the add-ons move on their own from Settings → Storage: see Where PhotoBlad keeps things.

Moving to another computer

From the next release, moving PhotoBlad to a new Mac (or to Windows, or to Docker) is restoring a copy of its database there, with the drives your photos are on brought along. Move PhotoBlad to another computer… on Settings → Storage lays out the move for your server, with the commands. In short: make a fresh copy (Settings → Health → Copy now), stop PhotoBlad on the old Mac and keep it stopped, bring the drives (a storage folder on the old Mac’s own disk, such as ~/PhotoBlad, is copied whole, for example with ditto), install PhotoBlad on the new Mac without creating the owner account, and run:

~/Applications/PhotoBlad/photoblad restore /Volumes/Drive/PhotoBlad/Uploads/.photoblad/database-copies/photoblad-<time>.zip

Add --root <folder> for each storage location that is in another folder than it was. Everyone’s accounts, albums, edits and connections come back, and connected PhotoBlads stay paired. Give the new Mac the old one’s name in Tailscale, or point your domain at it, so passkeys and phones keep working; if the name changes, Health says what to do. Self-hosting has every step, and photoblad move-data (above) is for moving the data on this Mac.

Removing PhotoBlad

photoblad uninstall removes the program, its background agents and the menu-bar icon. It never removes your photos or PhotoBlad’s data, and says where they are. Delete ~/.photoblad and ~/PhotoBlad yourself, after copying what you want to keep: they may hold the only copies of people’s photos.