Skip to content

Connection guide

Jump to bottom
Oleg Koretsky edited this page May 12, 2024 · 15 revisions

Once you've installed the gallery, it needs to be connected to your PhotoPrism library server. The gallery can be connected to both public and private libraries and supports extra authentication methods such as HTTP basic auth and mutual TLS (mTLS).

âš  Common errors are listed at the bottom.

Library root URL

The main parameter you need to enter is the library root URL. This is the main part of its website address before the /library part. On the following example, the root URL is highlighted in yellow:

Example

When you copy or manually type the root URL, make sure to include http:// or https:// part as well – this is important for the gallery app to know whether to use a secure connection.

If your library is accessible from a phone browser, then the gallery app should connect just fine. Note that if your server is only accessible from a local network, e.g. within your home Wi-Fi, the phone must be connected to the same network. Also, if you use a self-signed SSL certificate for your library, it must be installed to the phone as well.

The following examples show possible URLs for various use-cases:

Examples of valid URLs:

  • http://10.0.0.125:2342 – if you have no hostname and/or use a custom port
  • http://photoprism.local – if you have a hostname
  • https://myserver.io/ingress/photoprism – if your library is accessible at a non-root path, for example, when using Home Assistant
  • https://prism.myserver.io – if your library is accessible at a subdomain
  • https://username:password@myserver.io/photoprism – if your library requires HTTP basic auth

Examples of invalid URLs:

  • 10.0.0.125:2342 – missing the scheme, must be http://10.0.0.125:2342
  • https://admin@prism.local/originals/ – WebDAV URL, must be https://prism.local
  • https://prism.myserver.io/library/browse – Web app "Search" page, must be https://prism.myserver.io

Credentials

If you connect to your private library, enter the username and the password you use to access the website.

You can also connect to a public library, such as PhotoPrism public demo https://demo.photoprism.app, to test the app first. In this case, leave the username and the password fields empty.

Client certificate

If your library server is secured with a mutual TLS (mTLS) authentication, you need to select your installed client certificate in order to connect. Otherwise, leave the field empty.

Learn more about use of client certificates from a detailed mTLS guide.

Common errors

  • URL format is incorrect. Make sure it contains the protocol – you have to explicitly specify the https:// or http:// prefix for your libary root URL in order for the gallery app to know whether to use a secure connection. For example, change 192.168.100.122:2342 to http://192.168.100.122:2342.
  • Library is not accessible: HTTP 404 – a PhotoPrism library can't be found under the URL you've entered. Check if the library is accessible from a phone browser with the same URL. If redirects occur in the browser, use the final URL from the address bar.
  • Library is not accessible: JsonParseException or Library is not accessible: ProxyBlockingAccessException – it is most likely that you use a proxy (Nginx, Cloudflare, Traefic, etc.) which is not properly configured or can't reach your library server, therefore returning an HTML error page to calls expected to contain JSON. Check if the library is accessible from a phone browser with the same URL. If you use Cloudflare, make sure it doesn't require solving captcha or enforce Tunnel authentication.
  • Library is not accessible: SSL exception – the app can't establish a secure connection to your library because of SSL misconfiguration. There may not be a corresponding root certificate on the phone, or the server certificate chain may be incomplete, or you've specified the wrong port in the library root URL. Check if the library is accessible from a phone browser with the same URL. Then run an online SSL check, which may also point out the issue. If you use a self-signed certificate, follow this checklist. The app won't work with PhotoPrism default TLS
Clone this wiki locally