# Project pack: PhotoPrism @ 1c515fd Facts about **PhotoPrism** 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. > PhotoPrism turns a folder of family photos and videos into a private photo library you open in the browser. It sorts pictures by date and place, recognises faces and things like "beach" or "dog", and shows your trips on a world map. Share albums with relatives by link, and back up phones with a sync app. It runs on your own computer or NAS, so your pictures never go to a big tech company. ## Version and source - Repository: https://github.com/photoprism/photoprism - Pinned commit: `1c515fd6a6e89d917ccc318a96c8cc39ee8c4d8f`. 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/photoprism/photoprism/archive/1c515fd6a6e89d917ccc318a96c8cc39ee8c4d8f.zip - Official docs: https://docs.photoprism.app - Live demo: https://try.photoprism.app. Official public demo. Don't upload anything private. - Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (not just your own household), you must offer them your source code under the same licence. "PhotoPrism" and its logo are registered trademarks: a changed copy you share must not use the brand. Some extras are only for paying members. ## Running the pinned source - Fresh pinned-source setup (skip clone and checkout in an existing worktree): ```sh git clone https://github.com/photoprism/photoprism bespoke-photoprism cd bespoke-photoprism git checkout --detach 1c515fd6a6e89d917ccc318a96c8cc39ee8c4d8f # Prepare development requirements and local configuration first. # Setup notes: then inside the container: make dep build-js build-go && ./photoprism start make docker-build && docker compose up -d && make terminal ``` 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 mkdir photoprism && cd photoprism curl -fsSL -o compose.yaml https://dl.photoprism.app/docker/compose.yaml # edit compose.yaml first: change PHOTOPRISM_ADMIN_PASSWORD and the database passwords, # and point the originals volume at your photo folder docker compose up -d # then open http://localhost:2342 ``` - Needs: Docker with Docker Compose (64-bit Intel, AMD or ARM, including Raspberry Pi 4/5), At least 2 CPU cores and 3 GB RAM (more for large libraries and face recognition), For development, Docker plus the repo's Makefile (Go and Node run inside the dev container) - Develop: `make docker-build && docker compose up -d && make terminal # then inside the container: make dep build-js build-go && ./photoprism start` - Test: `make test-js test-go` - Check/lint: `make lint-js lint-go` - Stack: go, javascript, vue (Gin, GORM, Vue 3, Vuetify 3, TensorFlow and ONNX (local AI), FFmpeg, libvips). Difficulty for a non-developer with an AI: **advanced**. Settings, themes, wallpaper, sharing and the AI models are easy to change without code. The code is a large Go backend with a Vue 3 frontend, a Docker-based development environment and many build steps (models, FFmpeg, image libraries). Detailed AGENTS.md files and code maps help an AI find its way. ## The project's own AI instructions Read these in the repository before changing code: `AGENTS.md`, `CODEMAP.md`, `frontend/AGENTS.md`, `frontend/CODEMAP.md`, `.claude/CLAUDE.md`. ## Customisation points (settings → extend → code) - **library-settings** [settings]: Theme, language, start page, which features show (people, places, private, archive) and upload options. → `Settings → General / Content / Advanced in the app (frontend/src/page/settings/general.vue, content.vue, advanced.vue)` - **branding** [settings]: Call it "The Smith Family Photos", pick a colour theme and a login wallpaper. → `PHOTOPRISM_SITE_TITLE, PHOTOPRISM_SITE_CAPTION, PHOTOPRISM_DEFAULT_THEME, PHOTOPRISM_WALLPAPER_URI in compose.yaml (internal/config/flags.go); themes in frontend/src/options/themes.js` - **people-and-ai** [settings]: Name family members once and find every photo of them; optionally add AI captions with a local Ollama model. → `People page for naming faces; PHOTOPRISM_DISABLE_FACES, PHOTOPRISM_DETECT_NSFW; vision.yml in the storage config folder (internal/ai/vision/README.md)` - **sharing** [settings]: Send grandparents a link to an album without an account, or give family members their own logins. → `Album → Share (secret links with optional expiry); extra accounts with the photoprism users command (internal/commands/users.go)` - **phone-backup-and-webdav** [extend]: Back up phones with PhotoSync and open the library as a folder in Windows Explorer or Finder. → `Built-in WebDAV server (frontend/src/component/settings/webdav.vue); docs.photoprism.app user guide → Sync` - **api-cli-mcp** [extend]: Scripts for imports and albums, or let an AI assistant search your library for you. → `REST API (internal/api/), command line (internal/commands/), MCP endpoint at /api/v1/mcp (internal/mcp/README.md, internal/api/mcp.go)` - **frontend-pages** [code]: New or simpler views, for example a kiosk slideshow for a kitchen screen. → `frontend/src/page/, frontend/src/component/, styles in frontend/src/css/, text through frontend/src/locales/` - **backend-features** [code]: New behaviour on the server. Read the AGENTS.md in each folder first. → `internal/api/ (endpoints) → internal/photoprism/ (import and index) → internal/entity/ (data, migrations in internal/entity/migrate/)` ## Must keep working - Original photos and videos. Never let code move or delete originals without a backup; consider PHOTOPRISM_READONLY. - Privacy settings. Photos marked private and shared-link limits must keep working. - User and role permissions; one user must not see another's private photos. - Database changes need a migration in internal/entity/migrate/ (see its AGENTS.md). - The API used by the web app and sync apps. Add rather than change endpoints. - The trademark. A changed copy you share with others must not be called PhotoPrism or use its logo. ## Staying updatable Settings, themes, vision.yml, WebDAV, sharing, the API and MCP cover most family needs without a fork. Upstream welcomes AI for research and drafting but does not accept fully AI-generated pull requests; every change must be understood and maintained by a human, contributors sign a CLA, and AGENTS.md forbids AI co-author trailers in commits. Reviews can take months, so keep personal changes in your own copy. ## Data, costs and safety - Personal data: **yes**. Stored in: Your original photos stay in your own folder (originals volume). Thumbnails, sidecar files, settings and the SQLite option live in the storage volume; the index of albums, people and labels is in MariaDB (database volume). Back up the originals folder first, plus the storage folder. PhotoPrism makes daily database backups and YAML sidecar files for photos and albums, so the library can be rebuilt. Set PHOTOPRISM_READONLY=true if you want the originals folder never to be touched. - Service: PhotoPrism places service (geocoding) (optional, free): Turns photo GPS coordinates into place names. Coordinates are sent to PhotoPrism's own service; turn off with PHOTOPRISM_DISABLE_PLACES. - Service: Ollama (local) or OpenAI (optional, free with your own hardware, or pay-per-use with OpenAI): Optional captions and smarter labels from a vision AI model, set up in vision.yml. Built-in face and label recognition run locally without these. - Service: Phone sync app (PhotoSync or another WebDAV app) (optional, varies): Back up phone photos to PhotoPrism in the background. - Service: PhotoPrism membership (Essentials, Plus) (optional, paid subscription): Unlocks extra features such as interactive world maps and supports the project. - Setting `PHOTOPRISM_ADMIN_PASSWORD` (**secret**: the person enters it themselves, never in chat): First admin password (8 to 72 characters). Change it from 'insecure' before the first start. Never paste it into an AI chat. - Setting `PHOTOPRISM_SITE_URL`: The address you open PhotoPrism at, needed for share links. - Setting `PHOTOPRISM_DATABASE_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password. Must match MARIADB_PASSWORD in the mariadb service. - Setting `PHOTOPRISM_AUTH_MODE`: Leave as password (the default). Never use public on anything reachable from outside your home. - Setting `PHOTOPRISM_SITE_TITLE`: Title shown in the app and browser tab. PHOTOPRISM_SITE_CAPTION sets the tagline. - Setting `PHOTOPRISM_DEFAULT_THEME`: Default colour theme for new users. PHOTOPRISM_WALLPAPER_URI sets the login wallpaper. - Setting `PHOTOPRISM_DEFAULT_LOCALE`: Default interface language, e.g. en or de. - Setting `PHOTOPRISM_READONLY`: Set true so PhotoPrism never changes your original photo folder (some features are reduced). - Setting `PHOTOPRISM_DISABLE_FACES`: Turn face recognition off. - Setting `PHOTOPRISM_DISABLE_PLACES`: Stop sending GPS coordinates to the places service. - Setting `PHOTOPRISM_DISABLE_MCP`: Turns off the built-in MCP endpoint that lets signed-in AI assistants search your library. It is on by default. - Setting `OLLAMA_BASE_URL`: Address of your Ollama server for AI captions and labels. - Setting `OPENAI_API_KEY` (**secret**: the person enters it themselves, never in chat): Only if you choose OpenAI for captions or labels in vision.yml. - Change PHOTOPRISM_ADMIN_PASSWORD and the database passwords from 'insecure' before the first start, and never set PHOTOPRISM_AUTH_MODE to public on an internet-facing server. - Photos often show children, homes and locations. Use HTTPS and a reverse proxy before opening it to the internet; share links work for anyone who has them. - GPS coordinates are sent to PhotoPrism's places service unless you disable it. AI captions with OpenAI send your photos to OpenAI; Ollama keeps them local. - The MCP endpoint is on by default for signed-in users. Disable it with PHOTOPRISM_DISABLE_MCP if you don't use AI assistants. --- # Customising PhotoPrism PhotoPrism is a big Go and Vue application, but **most family wishes are settings**: names, themes, what shows in the menu, sharing and AI. Use code only for new screens, and keep it in your own copy. ## Level 1: Settings (no code) - **In the app (Settings):** theme, language, start page, which sections show (People, Places, Moments, Private, Archive), upload and download options. - **In `compose.yaml`:** `PHOTOPRISM_SITE_TITLE` and `PHOTOPRISM_SITE_CAPTION` (your family name), `PHOTOPRISM_DEFAULT_THEME`, `PHOTOPRISM_WALLPAPER_URI`, `PHOTOPRISM_DEFAULT_LOCALE`, `PHOTOPRISM_READONLY` (never touch originals), `PHOTOPRISM_DISABLE_FACES`, `PHOTOPRISM_DISABLE_PLACES`, `PHOTOPRISM_DISABLE_MCP`. Restart the container after changes. - **People:** name a face once on the People page and PhotoPrism finds the same person in other photos. - **Sharing:** Album → Share makes a secret link, with an optional expiry date. Extra user accounts are added with `photoprism users add` inside the container. - **AI captions and labels:** `vision.yml` in the storage `config` folder. Point it at a local Ollama model (`OLLAMA_BASE_URL`) or OpenAI (`OPENAI_API_KEY`). See `internal/ai/vision/README.md`. ## Level 2: Extend (no fork) - **WebDAV:** connect Windows Explorer, Finder or phone apps such as PhotoSync to upload and back up photos. - **Command line:** `docker compose exec photoprism photoprism index`, `import`, `backup`, `users` and more (`internal/commands/`). - **REST API:** documented at https://docs.photoprism.dev, implemented in `internal/api/`. - **MCP:** signed-in AI assistants can search media, albums, people and labels at `/api/v1/mcp` (`internal/mcp/README.md`). ## Level 3: Code Read `AGENTS.md`, `CODEMAP.md`, `frontend/AGENTS.md` and the `AGENTS.md` in the folder you change. | Change | Where | |---|---| | Pages | `frontend/src/page/` (e.g. `page/settings/general.vue`) | | Components | `frontend/src/component/` | | Colours and themes | `frontend/src/options/themes.js`, `frontend/src/css/` | | Text and translations | `frontend/src/locales/` (translations are managed upstream) | | Settings and options | `internal/config/` (`flags.go`, `options.go`) | | API endpoints | `internal/api/` | | Import and indexing | `internal/photoprism/` | | Data and migrations | `internal/entity/`, `internal/entity/migrate/` | ## Running locally - **Just use it:** download the official `compose.yaml` (see `bespoke.yaml`), change the passwords and photo folder, run `docker compose up -d`, then open http://localhost:2342. - **Develop:** 1. Install Docker. 2. In the repo, run `make docker-build` and `docker compose up -d`. 3. Run `make terminal` to open a shell in the dev container. 4. Inside it, run `make dep build-js build-go` and `./photoprism start`. - **Check:** `make test-js test-go` and `make lint-js lint-go` (inside the container). ## Pitfalls - Back up the originals folder and storage folder before upgrades or code changes. - Indexing a big library takes hours and lots of memory. Give the server swap space. - The community edition differs from paid editions; some features you read about need a membership. - Upstream does not accept fully AI-generated pull requests and asks for no AI co-author trailers. Keep personal code in your own copy, and don't use the PhotoPrism name or logo for a changed version you share. --- Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/photoprism/1c515fd/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/photoprism/1c515fd/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/photoprism/1c515fd/r2/SKILL.md)