Skip to content

Connection guide

Jump to bottom
Oleg Koretsky edited this page Oct 3, 2024 · 28 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, mutual TLS (mTLS) or SSO (Authelia, Cloudflare Access, etc.).

⚠️ The gallery doesn't work with PhotoPrism default TLS

⚠️ 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 address you use to access your library from a browser. It is not the WebDAV URL. On the following example, the root URL is highlighted in blue:

Example

When you copy or manually type the root URL, make sure to include http:// or https:// protocol 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 protocol, must be http://10.0.0.125:2342
  • https://admin@prism.local/originals/ – WebDAV URL, must be https://prism.local

Credentials

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

If you'd like to use a specific app password, make sure to set it up with the "Full access" level. Then use this password in combination with your admin username to connect:

Apps and devices

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.

SSO

If the gallery detects that a proxy (Authelia, Cloudflare Access, etc.) prevents access to the library by redirecting to a web page, the page will be shown in the internal browser. Authenticate there and once you are redirected back to PhotoPrism – the gallery catches it, saves the cookies and proceeds with the connection.

In case you use PhotoPrism+OIDC, you must create a dedicated app password for the gallery with the "Full access" level and then use it in combination with your admin username to connect.

Common errors

  • PhotoPrism login page appears – you've probably included the unnecessary /library/... part to your libary root URL. Remove it and try again.

  • 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, without security warnings
    • Run an online SSL check, which may also point out the issue
    • If you use a certificate issued by your own CA, follow this checklist
    • The gallery doesn't work with PhotoPrism default TLS
Clone this wiki locally