Skip to content

Setting Up Your Development Environment

Before you start, make sure you have Git and Docker installed on your system. Instead of using Docker, you can create your own development environment based on our Dockerfile (not recommended). You'll need Go >= 1.17, TensorFlow for C, Make, NPM, and MariaDB. Without Docker, test results will be less reliable and you also won't be able to use our other Dockerfiles (e.g. for TensorFlow).

Step 1: Run Git to clone this project:

git clone [email protected]:photoprism/photoprism.git

If you're on windows, make sure to disable auto CR LF. Otherwise, the build won't work. git config --global core.autocrlf false

Step 2: Start Docker containers:

cd photoprism
docker-compose up

Note: This docker-compose configuration is for testing and development purposes only.

Step 3: Open a terminal to the PhotoPrism container:

docker-compose exec photoprism bash

Now you can run commands inside this terminal. To run the Go webserver, run:

make all
./photoprism start

You can see a list of all make targets in our Makefile. For example, make test will run the tests and make install will build a photoprism production binary without debug information and install it in the user's directory including all assets.

Step 4: Build the frontend in watch mode:

The Go webserver will serve static assets in addition to providing the backend API. The static assets can be automatically built whenever you change a file. In a new terminal window, outside the Docker container, run:

make dep-js
make watch-js

PhotoPrism will now be available at localhost:2342. This is set in the docker-compose.yml.


  • Radomir Sohlich wrote a pragmatic introduction to Makefiles for Go developers.
  • We are using Go Modules for managing our dependencies (new in 1.11).
  • If you never used Go before and would like to learn it, you are welcome to reach out. We might start organizing regular learning sessions for beginners in Berlin.
  • This guide was not tested on Windows, you might need to change docker-compose.yml to make it work with Windows specific paths.

Apple M1 and Raspberry Pi

Our development environment has been built into a single multi-arch image for 64-bit AMD, Intel, and ARM processors. That means, Apple M1 and Raspberry Pi 3 / 4 owners can pull from the same repository.

Building multi-arch images

This works out of the box with Docker Desktop. Just run make docker-development-multiarch. If you want to build those images for different architectures on Linux, you need to setup docker buildx builder instances or setup QEMU on your machine which shall run your builds. More info can be found in the docker docs: Docker Buildx, Leverage multi-CPU architecture support

QEMU Quick Start

  1. install qemu-user-static from docker hub: docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
  2. verify that dockers buildx command is installed docker buildx version. if missing, follow install instructions here
  3. create buildx builder: docker buildx create --name multiarch-builder && docker buildx inspect --builder multiarch-builder --bootstrap
  4. start building: make docker-development-multiarch or make docker-photoprism-multiarch

Alternate Development Environments

The following are setup instructions for development and testing and should be avoided unless Docker is either not supported or not allowed in your environment: