# Project pack: LibrePhotos @ 14b4523

Facts about **LibrePhotos** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> LibrePhotos is a self-hosted photo and video manager, an alternative to Google Photos. It scans your folders, groups pictures by people with face recognition, places on a map, events and scenes, and offers search, albums and sharing. It is built for people who want smart features without the cloud.

## Version and source
- Repository: https://github.com/LibrePhotos/librephotos
- Pinned commit: `14b452385fa390ec2b221c5e335c42498467137a`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/LibrePhotos/librephotos/archive/14b452385fa390ec2b221c5e335c42498467137a.zip
- Official docs: https://docs.librephotos.com
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/LibrePhotos/librephotos bespoke-librephotos
  cd bespoke-librephotos
  git checkout --detach 14b452385fa390ec2b221c5e335c42498467137a
  # Prepare development requirements and local configuration first.
  cd apps/frontend
  npm install
  npm run dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  Follow the installation guide at https://docs.librephotos.com/installation/standard-install, which provides a docker-compose.yml with the librephotos images.
  ```

- Needs: Docker with 8 GB or more of memory and a lot of disk space; Python and Node for development
- Develop: `cd apps/frontend && npm run dev`
- Stack: python, typescript (Django, Django REST Framework, React, Vite, Docker). Difficulty for a non-developer with an AI: **advanced**. A Django back end with machine-learning jobs and a React front end, plus docs and a mobile app in the same repository. Library settings are easy; changes to the pipeline are heavy.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`.

## Customisation points (settings → extend → code)
- **library-and-scan** [settings]: Which folders are scanned and how often. → `Settings → Library and Scan`
- **people-and-albums** [settings]: Name faces and group photos by event or place. → `People, Albums and Auto albums in the app`
- **sharing** [settings]: Public links and shared albums for family. → `Settings → Sharing`
- **backend-jobs** [code]: Face recognition, scene and album tasks. → `apps/backend/api`
- **react-ui** [code]: Screens and photo views. → `apps/frontend/src`

## Must keep working
- Never modify or delete original photo files unless the user asks.
- Django migrations. Add new ones; never edit old ones.
- Sharing and permission checks.

## Staying updatable
Use settings and sharing. Put pipeline changes in new tasks and keep UI changes in new components.

## Data, costs and safety
- Personal data: **yes**. Stored in: A Postgres database plus a cache of thumbnails and models; your originals stay in your photo folder. Photos hold faces and locations. Back up your originals and the database.
- Service: Reverse geocoding (Mapbox or OpenStreetMap) (optional, free tier): Turn photo locations into place names.
- Setting `SECRET_KEY` (**secret**: the person enters it themselves, never in chat): Django secret key. Never paste it into an AI chat.
- Setting `DB_PASS` (**secret**: the person enters it themselves, never in chat): Database password.
- Setting `MAPBOX_API_KEY` (**secret**: the person enters it themselves, never in chat): Optional key for map labels. Never paste it into an AI chat.
- Photos and faces are very private. Use HTTPS, strong passwords and encrypted backups.
- Don't expose it to the internet without a reverse proxy.

---

# Customising LibrePhotos

LibrePhotos is a monorepo with a Django back end, a React front end and docs. Its repo includes AGENTS.md and CLAUDE.md.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Django project and API | apps/backend/api/ |
| Machine-learning services | apps/backend/image_similarity/ and apps/backend/service/ |
| Web app | apps/frontend/src/ |
| Mobile app | apps/mobile/ |
| Documentation | apps/docs/ |
| Deployment | deploy/ |

## Use the gentlest change first

1. **Settings (no code):** libraries, scan, people, albums and sharing.
2. **Extend:** the REST API.
3. **Code:** tasks and screens.

## Recipes

- **New auto-album rule:** add the rule in the album task and expose the setting on the Albums page.
- **New photo filter:** add a query parameter in the API and a control in the filter bar.

## Running and checking your changes

- Start the stack, scan a folder of 20 photos and check faces, places and search.
- Run the Django tests and the front-end checks for the area you changed.

## Pitfalls

- Face recognition models are large and slow. Test with a small folder.
- Mount your originals read-only when testing.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/librephotos/14b4523/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/librephotos/14b4523/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/librephotos/14b4523/r2/SKILL.md)