photoview

Photoview is a simple and user-friendly photo gallery that's made for photographers and aims to provide an easy and fast way to navigate directories, with thousands of high-resolution photos.

You configure Photoview to look for photos and videos within a directory on your file system. The scanner automatically picks up your media and starts to generate thumbnail images to make browsing super fast.

When your media has been scanned, they show up on the website, organised in the same way as on the filesystem.

If you have questions regarding setup or development, feel free to join the Discord server https://discord.gg/jQ392948u9

ATTENTION to Docker users !!!

We migrated to the new Docker registry https://hub.docker.com/r/photoview/photoview, and all new images for the master tag as well as future releases will be published there instead of the previously used registry. Old images will still be accessible in the old registry https://hub.docker.com/r/viktorstrate/photoview, so if you want to use one of those older images, revert to the old registry.

Please update your docker-compose.yml file to use the new registry for the photoview image, as shown in the corresponding example of the compose file: https://github.com/photoview/photoview/tree/master/docker-compose%20example

ATTENTION to PostgreSQL users !!!

We switched to PostgreSQL 18 on the master branch. PostgreSQL 18 will be the default recommended version for the next release (PostgreSQL 17 remains supported). If you follow master, please check the official PostgreSQL upgrade guide, and:

• For Docker users: please update your docker-compose.yml to match docker-compose.example.yml.
• Please pay attention to the DB volume mount point change inside the container: starting from version 18, the DB is mounted to the /var/lib/postgresql, while in earlier versions it was the /var/lib/postgresql/data.
• For direct host installations or external/shared PostgreSQL instances: please upgrade your PostgreSQL server and database manually to version 18 following PostgreSQL guidance.

Don't forget to back up your database before upgrading.

Demo site

Visit https://photos.qpqp.dk/

Username: demo

Password: demo

Contents

• ATTENTION to Docker users !!!
• ATTENTION to PostgreSQL users !!!
  • Demo site
  • Contents
  • Main features
  • Supported platforms
  • Supported databases
  • Why yet another self-hosted photo gallery
  • Getting started — Setup with Docker
    • Initial Setup
  • Advanced setup
    • Hardware Acceleration
  • Contributing
  • Set up Docker development environment
    • Start API and UI server with Docker Compose
    • Start API server with Docker
    • Start UI server with Docker
  • Set up local development environment
    • Install dependencies
    • Local setup
    • Start API server
    • Start UI server
  • Sponsors

Main features

• Closely tied to the file system. The website presents the images found on the local filesystem of the server; directories are mapped to albums.
• User management. Each user is created along with a path on the local filesystem, photos within that path can be accessed by that user.
• Sharing. Albums, as well as individual media, can easily be shared with a public link, the link can optionally be password protected.
• Made for photography. Photoview is built with photographers in mind, and thus supports RAW file formats, and EXIF parsing.
• Video support. Many common video formats are supported. Videos will automatically be optimized for web.
• Face recognition. Faces will automatically be detected in photos, and photos of the same person will be grouped together.
• Performant. Thumbnails are automatically generated and photos first load when they are visible on the screen. In full screen, thumbnails are displayed until the high-resolution image has been fully loaded.
• Secure. All media resources are protected with a cookie-token, all passwords are properly hashed, and the API uses a strict CORS policy.

Supported platforms

• Docker (Docker Engine released within the last year and a major version not older than the previous one).

  [!NOTE] We don’t support Portainer or other abstraction layers on top of Docker Compose. If you encounter an issue, please reproduce it on the setup with plain Docker Compose before reporting.

• Debian Linux 12 and 13, Ubuntu Linux LTS and newer short-term releases
• Arch Linux AUR
• NixOS (PR, Nixpkgs, NixOS options)
• Unraid
• EmbassyOS: announcement, repo
• YunoHost
• TrueNAS

We provide limited support for the standard deployment scenarios on the platforms above. The project team has no testing environments for all of them, so assistance is based on user-provided logs and traces. Highly customized setups may further limit our ability to help.

Supported databases

• SQLite: built-in DBMS, no additional service or maintenance required; lowest performance and no scalability.
• MariaDB LTS version: default choice. Runs as an additional service; good balance between performance and maintenance effort.
• PostgreSQL 18 and 17: typically the best performance. Runs as an additional service; requires slightly more maintenance.

We support running Photoview with one of these DBMSs when used as a dedicated instance for Photoview only. If you share a DBMS among multiple services, our support is limited to SQL issues. DB management and connection-related issues are the user’s responsibility due to the variability of shared configurations.

Why yet another self-hosted photo gallery

There exists a lot of open-source self-hosted photo galleries already. Here are some, just to mention a few.

• Piwigo
• LibrePhotos
• Photoprism
• Lychee

So why another one? I love taking photos, and I store all of them on my local fileserver. This is great because I can organize my photos directly on the filesystem, so it's easy to move them or take backups. I want to be able to control where and how the photos are stored.

The problem is, however, that RAW images are extremely tedious to navigate from a fileserver, even over the local network.

My server holds a lot of old family pictures that I would like my family to have access to as well. And some of the pictures I would like to easily be able to share with other people without the hassle of them having to make an account first.

Thus, I need a solution that can do the following:

• A scan-based approach that automatically organises my photos
• Support RAW and EXIF parsing
• Have support for multiple users and ways to share albums and photos also publicly
• Be straightforward and fast to use

All the photo galleries can do a lot of what I need, but no single one can do it all.

Getting started — Setup with Docker

This section describes how to get Photoview up and running on your server with Docker. Make sure you have Docker and docker-compose installed and running on your server. make should be installed as well if you'd like to use provided Makefile, which is optional (see step 4 for more details). 7zz should be installed in case, you'd like to use it in scope of the backup scenario instead of the default .tar.xz format. Read the comment in the Makefile, located on top of the backup section for more details.

1. Download the content of the docker-compose example folder to the folder on your server, where you expect to host the Photoview internal data (database and cache files).

   Please note that this folder contains 2 versions of the docker-compose file:

   • docker-compose.example.yml - the fully-functional and recommended for the most cases config
   • docker-compose.minimal.example.yml - the minimal and simple config for those, who find the previous one too complex and difficult to understand and manage

   When downloading files, you need to choose only one of them.

2. Rename downloaded files and remove the example from their names (so, you need to have .env, docker-compose.yml, and Makefile files). If you choose the docker-compose.minimal.example.yml on previous step, make sure to rename it to the docker-compose.yml.

3. Open these files in a text editor and read them. Modify where needed according to the documentation comments to properly match your setup. There are comments of 2 types: those, starting with ##, are explanations and examples, which should not be uncommented; those, starting with #, are optional or alternative configuration parts, which might be uncommented in certain circumstances, described in corresponding explanations. It is better to go through the files in the next order: .env, docker-compose.yml, and Makefile.

   If your PGSQL_PASSWORD or MARIADB_PASSWORD contain special characters (e.g., @), make sure to URL-encode them, e.g., p@ss → p%40ss.

4. Make sure that your media library's root folder and all the files and subfolders are readable and searchable by other users: run the next command (or corresponding sequence of commands from the Makefile):

   make readable
   

   If command(s) return Permission denied error, run them under the user owning corresponding files and folders. Alternatively, prefix them with sudo: this switches the execution context to root and typically prompts for your own password (unless configured otherwise). You must have sudo privileges to do this.

   If you don't want to give required permissions to others group for your files, alternatively, you can:

   • create a group on your host with GID=999 and make all the files and folders inside volumes of the photoview service being owned by this group; then set the appropriate permissions to the group section.
   • create on your host a group with GID=999 and a user in this group with UID=999; then change the ownership of all the files and folders inside volumes of the photoview service to this user; then set the appropriate permissions to the user section.

   If you configured other mounts with media files from other locations on the host (like HOST_PHOTOVIEW_MEDIA_FAMILY or anything else), you need to run the same commands, as in the Makefile readable target, for each media root folder on your host manually: copy ea