Skip to content

About

Self-hosted photo server for Windows: an iPhone sends new photos over home Wi-Fi through Apple Shortcuts, no app needed, and an optional native Android app does the same, with a verified-hash cleanup and a gallery.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

photo-harbor

Photo-Harbor social preview

License AIKit Integrated

Self-hosted photo server for Windows: an iPhone sends new photos over home Wi-Fi through Apple Shortcuts, no app needed, and an optional native Android app does the same, with a verified-hash cleanup and a gallery.

For detailed usage, see How It Works, Performance, Limits, and Full API Reference.

⚡ 30-Second Cold-Start Quick Reference

  • Runtime Prerequisites: Python 3.10 or newer (standard library only). Optional: pip install pillow pillow-heif for HEIC thumbnails and camera details.
  • Canonical Regression Shield Gate:
    python -m unittest discover -s tests -t .
  • Try it now (from this folder): double-click Harbor.pyw and press Start server, then Open photo browser (or double-click Open Photo Browser.url). From a console:
    python -m photo_harbor serve
    The first time, choose Sign in with a key instead and paste the main key shown in the window (or printed by serve), then set a password under Setup → My account. When Windows Firewall asks, allow Python on Private networks so the iPhone can reach it.

🛠️ AIKit Commands (run from the AIKit folder)

Role Command
Status, task and gates python aikit.py status photo-harbor
Phase 4: every gate python aikit.py check photo-harbor
Repair memory and map, then check python aikit.py fix photo-harbor
Resume an interrupted task python aikit.py resume photo-harbor

📦 What's Inside

photo-harbor/
├── .aikit/                   <- project memory: record, ledger, decisions, state machines
├── .gitignore
├── Harbor.pyw                <- double-click: the Harbor window (Start/Stop server)
├── LICENSE                   <- Aegean License 1.1 (AL-1.1): free personal use
├── LICENSES/                 <- REUSE license texts
├── REUSE.toml                <- Machine-readable SPDX metadata
├── Open Photo Browser.url    <- double-click: the gallery at http://localhost:8642
├── README.md
├── assets/
├── android/                  <- native Android client, build.py and install page source
├── COMMERCIAL.md
├── docs/                      <- extended documentation
│   ├── API.md                 <- HTTP API reference
│   ├── HOW_IT_WORKS.md       <- detailed feature descriptions
│   ├── LIMITS.md              <- known limitations
│   ├── PERFORMANCE.md         <- performance benchmarks
│   └── STRUCTURE.md           <- full project structure
├── photo_harbor/
│   ├── __init__.py           <- package version
│   ├── __main__.py           <- `python -m photo_harbor` commands
│   ├── app.py                <- wires storage, APIs and the web page into routes
│   ├── atomic_file.py        <- temp + fsync + replace, and exclusive placement
│   ├── accounts.py           <- password hashes, sessions, wrong-password brake
│   ├── activity_api.py       <- read-only recent journal events
│   ├── albums.py             <- personal albums and favorites; no files move
│   ├── albums_api.py         <- albums and favorites API
│   ├── archive.py            <- per-person hidden photos; no files move
│   ├── archive_api.py        <- archive/restore API
│   ├── auth.py               <- home-network check; key/session sign-in
│   ├── autostart.py          <- start with Windows (per-user Run key)
│   ├── backup.py             <- mirror to a second drive, daily thread
│   ├── backup_api.py         <- owner-only backup status
│   ├── body_readers.py       <- Content-Length and chunked request bodies
│   ├── catalog.py            <- index of stored originals by SHA-256
│   ├── copies.py             <- whose folder holds which photo, and where
│   ├── config.py             <- settings file with the library key
│   ├── control_panel.py      <- the Harbor window (tkinter)
│   ├── database.py           <- SQLite file and its format version
│   ├── details.py            <- file facts and optional EXIF
│   ├── downloads.py          <- one-off stored ZIPs with size limits and tokens
│   ├── downloads_api.py      <- prepare and serve downloads
│   ├── errors.py             <- the Error/Why/Fix triad
│   ├── exif_dates.py         <- capture date from EXIF, when Pillow is installed
│   ├── folders_api.py        <- read-only person/year/month folder tree
│   ├── geo.py                <- GPS point from EXIF, when Pillow is installed
│   ├── http_server.py        <- HTTP handling, byte ranges, security headers
│   ├── importer.py           <- copy photos in from disk, skip-list
│   ├── journal.py            <- uploads, finished syncs, photos reported missing, scans
│   ├── layout.py             <- person folders, guide file, old-layout migration
│   ├── library_api.py        <- status, outline, filtered photo list, originals, previews
│   ├── messages.py           <- Request and Reply values, JSON body reading, Range parsing
│   ├── naming.py             <- safe file names, month folders, media types
│   ├── phash.py              <- optional perceptual difference hash
│   ├── pillow_support.py     <- optional Pillow and HEIC loading
│   ├── profiles.py           <- people, folder ids and keys
│   ├── profiles_api.py       <- list, add, rename and re-key people
│   ├── records.py            <- frozen value objects
│   ├── router.py             <- method + path routing
│   ├── runner.py             <- start and stop a server in the background
│   ├── scan.py               <- keeping up with File Explorer; weekly file check
│   ├── selection.py          <- bulk hash parsing and validation
│   ├── setup_api.py          <- address and key for the Setup tab
│   ├── sidecar.py            <- read-only JSON/XMP sidecar ZIPs
│   ├── similar_api.py        <- read-only perceptual-hash groups and scan
│   ├── similar_builder.py    <- background cached-group rebuild
│   ├── store.py              <- hash-verified ingest and re-verification
│   ├── sync_api.py           <- the endpoints the Shortcuts call
│   ├── tags.py               <- personal tags and their photo marks
│   ├── tags_api.py           <- list, create, rename, delete and mark tags
│   ├── thumbs.py             <- optional Pillow previews, background warmer, cache pruning
│   ├── trash.py              <- move a copy aside, restore through ingest, delete forever
│   ├── trash_api.py          <- list, move, restore, delete and empty the trash
│   └── web/                  <- gallery, icons, PWA sw.js and android install page
└── tests/
    ├── __init__.py
    ├── library_fixture.py    <- a throwaway library for tests
    ├── test_activity.py      <- recent journal events and visibility
    ├── test_albums.py        <- personal albums, favorites and migration
    ├── test_archive.py       <- per-person archive and migration
    ├── test_cameras.py       <- camera EXIF and filtering
    ├── test_dates.py         <- date-range narrowing
    ├── test_details.py       <- file facts and optional EXIF
    ├── test_downloads.py     <- ZIP names, tokens and expiry
    ├── test_http.py          <- server over real socket
    ├── test_folder_view.py   <- read-only folder tree and visibility
    ├── test_folders.py
    ├── test_hashes.py        <- select matching across filters
    ├── test_lenses.py        <- lens filtering
    ├── test_messages.py
    ├── test_naming.py
    ├── test_parts.py
    ├── test_places.py       <- GPS extraction and filtering
    ├── test_profiles.py
    ├── test_runner.py
    ├── test_scale.py
    ├── test_records.py
    ├── test_search.py       <- multi-word search
    ├── test_sidecar.py      <- JSON/XMP sidecar ZIPs
    ├── test_similar.py      <- perceptual hashes and grouping
    ├── test_sort.py         <- newest, oldest, largest, smallest order
    ├── test_storage.py      <- whole-library and per-person storage totals
    ├── test_store.py
    ├── test_tags.py         <- personal tags and migration
    └── test_trash.py        <- move, restore, delete and migration

Library layout: <Person>\<YYYY>\<YYYY-MM>\<original name> holds the originals untouched, next to READ ME - Harbor.txt. Libraries from earlier versions (photos\...) are moved into this layout file by file the first time the server starts. The hidden .harbor\ holds config.json, catalog.sqlite3 (format 13; an older catalog is upgraded in place after a copy to catalog.sqlite3.v<N>.bak), incoming\, thumbs\ and trash\.

🚀 Performance

See Performance for detailed benchmarks.

⚠️ Limits

See Limits for known limitations.

📜 License

Free for personal use under the Aegean License 1.1 (AL-1.1); see LICENSE. Any commercial use needs the Aegean Commercial License 1.0 (ACL-1.0); see COMMERCIAL.md.

🎨 Brand Assets

AI-Generated Brand Artwork. The banner and logo are AI-generated brand assets. They are illustrative and may not literally depict every feature or the full project scope.

Screenshots

Photo Harbor sign-in at 2026-11-03

commit c73fa38 · 2026-11-03 · viewport 1440x900 · first-run gate; gallery views withheld (personal library, no demo mode — ADR-030)

About

Self-hosted photo server for Windows: an iPhone sends new photos over home Wi-Fi through Apple Shortcuts, no app needed, and an optional native Android app does the same, with a verified-hash cleanup and a gallery.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages