Installing and Running

The easiest way to run it is with Docker Compose using the pre-built image following these steps.

Installing Docker and Docker Compose

You'll first need to install Docker and Docker Compose if you don't already have them.

Installing these on recent versions of Debian, Ubuntu or Raspberry Pi OS can be done with the following commands and then logging out and back in.

sudo apt update
sudo apt install docker-compose
sudo usermod -aG docker $USER

If usermod is not available on your system then you can do it the manual way and edit /etc/group adding your username to end of the line that starts with docker:.

Finally check Docker is running and you have the right permissions by running the following. You should see some table headings beginning with CONTAINER ID but you won't have any actual containers running yet.

docker ps

If you still don't have permission, you may need to restart the whole machine.

Setting up

Create a new directory to run inside.

mkdir photonix
cd photonix

Download the example Docker Compose file. This works for x86/amd64 and arm32/arm64/Raspberry Pi architectures.

curl > docker-compose.yml

Make volume directory for photo data to be stored outside the container.

mkdir -p data/photos


Bring up Docker Compose which will pull and run the required Docker images.

docker-compose up -d

The above command will run the service in the background. Instead, if you want to watch the logs (useful for debugging problems) you can use the following.

docker-compose up

A few seconds after starting you should be able to go to http://localhost:8888/ in your browser.

When you first access Photonix it will guide you through the process of creating an admin user, password and your first library.

You can move some photos into the folder data/photos and they should get detected and imported immediately. Once you have finished trying out the system you can edit the volume in the docker-compose.yml file where it says ./data/photos to mount wherever you usually keep photos. System database, thumbnails and other cache data is stored separately from the photos so shouldn't pollute the area. You are responsible for keeping your own backups in case of error.

You can add extra users and libraries but this needs to be done on the command-line right now so run this in a new terminal window. Replace USERNAME with your own username.

docker-compose run photonix python photonix/ createsuperuser --username USERNAME --email
docker-compose run photonix python photonix/ create_library USERNAME "My Library"