From 315b49c1e6e499929543ddeedec0be90501116ab Mon Sep 17 00:00:00 2001 From: Michael Mayer Date: Sun, 16 Nov 2025 09:06:12 +0100 Subject: [PATCH] Config: Add fallback to load defaults from "config/defaults.yml" #5325 Config.DefaultsYaml() resolves the default options YAML file. When PHOTOPRISM_DEFAULTS_YAML points to a readable file it will be used; otherwise it falls back to `defaults.{yml,yaml}` inside the active config directory. This allows instances without `/etc/photoprism/defaults.yml` to still load local defaults, e.g., in containerized environments. Signed-off-by: Michael Mayer --- internal/config/README.md | 24 +++++++++++++++++++++--- internal/config/config_storage.go | 14 ++++++++++---- setup/pkg/linux/README.html | 6 ++++-- setup/pkg/linux/README.md | 18 +++++++++--------- 4 files changed, 44 insertions(+), 18 deletions(-) diff --git a/internal/config/README.md b/internal/config/README.md index d5f92c06a..a71498b7d 100644 --- a/internal/config/README.md +++ b/internal/config/README.md @@ -9,19 +9,37 @@ PhotoPrism’s runtime configuration is managed by this package. Fields are defi PhotoPrism loads configuration in the following order: 1. **Built-in defaults** defined in this package. -2. **`defaults.yml`** — optional system defaults (typically `/etc/photoprism/defaults.yml`). See [Global Config Defaults](https://docs.photoprism.app/getting-started/config-files/defaults/) if you package PhotoPrism for other environments and need to override the compiled defaults. +2. **`defaults.yml`** — optional system defaults. PhotoPrism first checks `/etc/photoprism/defaults.yml` (or `.yaml`). If that file is missing or empty, it automatically falls back to `storage/config/defaults.yml` (respecting `.yml` / `.yaml` as well) under `PHOTOPRISM_CONFIG_PATH`. See [`defaults.yml`](https://docs.photoprism.app/getting-started/config-files/defaults/) if you package PhotoPrism for other environments and need to override the compiled defaults. 3. **Environment variables** prefixed with `PHOTOPRISM_…` and specified in [`flags.go`](flags.go) along with the CLI flags. This is the primary override mechanism in container environments. -4. **`options.yml`** — user-level configuration stored under `storage/config/options.yml` (or another directory controlled by `PHOTOPRISM_CONFIG_PATH`). Values here override both defaults and environment variables, see [Config Files](https://docs.photoprism.app/getting-started/config-files/). +4. **`options.yml`** — user-level configuration stored under `storage/config/options.yml` (or another directory controlled by `PHOTOPRISM_CONFIG_PATH`). Values here override both defaults and environment variables, see [`options.yml`](https://docs.photoprism.app/getting-started/config-files/). 5. **CLI flags** (for example `photoprism --cache-path=/tmp/cache`). Flags always win when a conflict exists. The `PHOTOPRISM_CONFIG_PATH` variable controls where PhotoPrism looks for YAML files (defaults to `storage/config`). > Any change to configuration (flags, env vars, YAML files) requires a restart. The Go process reads options during startup and does not watch for changes. +## Inspect Before Editing + +Before changing environment variables or YAML files, run `photoprism config | grep -i ` to confirm the current value of a flag, such as `site-url`, or `site` to show all related values: + +```bash +photoprism config | grep -i site +``` + +Example output: + +| Name | Value | +|:------------|:--------------------------| +| site-url | https://app.localssl.dev/ | +| site-https | true | +| site-domain | app.localssl.dev | +| site-author | @photoprism_app | +| site-title | PhotoPrism | + ## CLI Reference - `photoprism help` (or `photoprism --help`) lists all subcommands and global flags. -- `photoprism show config` renders every active option along with its current value. Pass `--json`, `--md`, `--tsv`, or `--csv` to change the output format. +- `photoprism show config` (alias `photoprism config`) renders every active option along with its current value. Pass `--json`, `--md`, `--tsv`, or `--csv` to change the output format. - `photoprism show config-options` prints the description and default value for each option. Use this when updating [`flags.go`](flags.go). - `photoprism show config-yaml` displays the configuration keys and their expected types in the [same structure that the YAML files use](https://docs.photoprism.app/getting-started/config-files/). It is a read-only helper meant to guide you when editing files under `storage/config`. - Additional `show` subcommands document search filters, metadata tags, and supported thumbnail sizes; see [`internal/commands/show.go`](../commands/show.go) for the complete list. diff --git a/internal/config/config_storage.go b/internal/config/config_storage.go index a18abfb73..166352ab8 100644 --- a/internal/config/config_storage.go +++ b/internal/config/config_storage.go @@ -257,17 +257,23 @@ func (c *Config) ConfigPath() string { // It relies on fs.ConfigFilePath so legacy `.yml` files keep working while // newly created instances may use `.yaml` without additional wiring. func (c *Config) OptionsYaml() string { - configPath := c.ConfigPath() - if c.options.OptionsYaml == "" { - return fs.ConfigFilePath(configPath, "options", fs.ExtYml) + return fs.ConfigFilePath(c.ConfigPath(), "options", fs.ExtYml) } return fs.Abs(c.options.OptionsYaml) } -// DefaultsYaml returns the default options YAML filename. +// DefaultsYaml resolves the default options YAML file. When +// PHOTOPRISM_DEFAULTS_YAML points to a readable file we use it; otherwise we +// fall back to `defaults.{yml,yaml}` inside the active config directory. +// This allows instances without `/etc/photoprism/defaults.yml` to +// load local defaults, e.g., in containerized environments. func (c *Config) DefaultsYaml() string { + if !fs.FileExistsNotEmpty(c.options.DefaultsYaml) { + return fs.ConfigFilePath(c.ConfigPath(), "defaults", fs.ExtYml) + } + return fs.Abs(c.options.DefaultsYaml) } diff --git a/setup/pkg/linux/README.html b/setup/pkg/linux/README.html index c0befe738..def160e69 100644 --- a/setup/pkg/linux/README.html +++ b/setup/pkg/linux/README.html @@ -30,7 +30,9 @@ button, input, select, textarea { color: inherit; font: inherit; } input[type="checkbox"], input[type="radio"] { line-height: normal; padding: 0px; } *, ::after, ::before { box-sizing: border-box; } #write h1, #write h2, #write h3, #write h4, #write h5, #write h6, #write p, #write pre { width: inherit; position: relative; } -#write svg h1, #write svg h2, #write svg h3, #write svg h4, #write svg h5, #write svg h6, #write svg p { position: static; white-space: nowrap; overflow: visible; } +#write svg h1, #write svg h2, #write svg h3, #write svg h4, #write svg h5, #write svg h6, #write svg p { position: static; } +.nodeLabel p { padding-right: 2px; padding-left: 2px; } +.typora-export .nodeLabel p { padding-right: 0px; padding-left: 0px; } foreignobject { overflow: visible; } p { line-height: inherit; } h1, h2, h3, h4, h5, h6 { break-after: avoid-page; break-inside: avoid; orphans: 4; } @@ -696,6 +698,6 @@ header, .context-menu, .megamenu-content, footer{ README
-

PhotoPrism® Installation Packages

As an alternative to our Docker images, you can use the packages available at dl.photoprism.app/pkg/linux/ to install PhotoPrism on compatible Linux distributions without building it from source.

These binary installation packages are intended for experienced users and maintainers of third-party integrations only, as they require manual configuration and do not include tested system dependencies. Since we are unable to provide support for custom installations, we recommend using one of our Docker images to run PhotoPrism on a private server or NAS device.

Also note that the minimum required glibc version is 2.35, so for example Ubuntu 22.04 and Debian Bookworm will work, but older Linux distributions may not be compatible.

Usage

Installation Using tar.gz Archives

You can download and install PhotoPrism in /opt/photoprism by running the following commands:

If your server has an ARM-based CPU, please make sure to install arm64.tar.gz instead of amd64.tar.gz when using the commands above. Both are linked to the latest stable release.

Since the packages currently do not include a default configuration, we recommend that you create a defaults.yml in /etc/photoprism next, in which you configure the paths and other settings that you want to use for your instance.

.deb Packages for Ubuntu / Debian Linux

As an alternative to the plain tar.gz archives, that you need to unpack manually, we also offer .deb packages for Debian-based distributions such as Ubuntu Linux. They install PhotoPrism under /opt/photoprism, add a /usr/local/bin/photoprism symlink, create /etc/photoprism/defaults.yml, and pull in the runtime libraries listed in the Dependencies section.

On servers with a 64-bit Intel or AMD CPU, our latest stable release can be installed as follows:

If your server has an ARM-based CPU, such as a Raspberry Pi, use the following commands instead:

Omit --no-install-recommends if you want APT to install MariaDB, Darktable, RawTherapee, ImageMagick, and other recommended extras automatically.

.rpm Packages for Fedora / RHEL / openSUSE

For RPM-based distributions we publish .rpm packages that mirror the layout described above. Install the latest release on x86_64 hardware with:

and on aarch64 (ARM64):

Replace dnf with zypper on openSUSE (use --allow-unsigned-rpm when required). On distributions that do not ship FFmpeg in the base repositories, enable the appropriate multimedia repository (EPEL, RPM Fusion, Packman, …) before installing the dependencies below.

AUR Packages for Arch Linux

Thomas Eizinger additionally maintains AUR packages for installation on Arch Linux. They are based on our tar.gz packages and have a systemd integration so that PhotoPrism can be started and restarted automatically.

Learn more ›

Updates

To update your installation, please stop all running PhotoPrism instances and make sure that there are no media, database, or custom config files in the /opt/photoprism directory. You can then delete its contents with the command sudo rm -rf /opt/photoprism/* and install a new version as shown above.

If you have used a .deb package for installation, you may need to remove the currently installed photoprism package by running sudo dpkg -r photoprism before you can install a new version with sudo apt install ./package.deb or sudo dpkg -i package.deb.

Dependencies

PhotoPrism packages bundle TensorFlow 2.18.0 and, starting with the October 2025 builds, ONNX Runtime 1.22.0 as described in ai/face/README.md. The shared libraries for both frameworks are shipped inside /opt/photoprism/lib, so no additional system packages are needed to switch PHOTOPRISM_FACE_ENGINE to onnx. The binaries still rely on glibc ≥ 2.35 and the standard C/C++ runtime libraries (libstdc++6, libgcc_s1, libgomp1, …) provided by your distribution.

Required Runtime Packages

Install the following packages before running PhotoPrism so that thumbnailing, metadata extraction, and the SQLite fallback database work out of the box:

Distribution familyCommand
Debian / Ubuntusudo apt install libvips42t64 libimage-exiftool-perl ffmpeg sqlite3 tzdata
Use libvips42 or, as a fallback, libvips-dev on older releases.
Fedora / RHEL / Alma / Rockysudo dnf install vips perl-Image-ExifTool ffmpeg sqlite tzdata
openSUSEsudo zypper install vips perl-Image-ExifTool ffmpeg sqlite3 tzdata

These packages pull in the full libvips stack (GLib, libjpeg/libtiff/libwebp, archive/zstd, etc.) that the PhotoPrism binary links against. Run ldd /opt/photoprism/bin/photoprism if you need to diagnose missing libraries on custom distributions.

For extended RAW processing, HEIF/HEIC support, and database scalability we recommend installing:

  • MariaDB or MariaDB Server (external database)

  • Darktable and/or RawTherapee (RAW converters)

  • ImageMagick (CLI utilities)

  • libheif (prefer the up-to-date binaries from dl.photoprism.app/dist/libheif/; install with bash <(curl -s https://raw.githubusercontent.com/photoprism/photoprism/develop/scripts/dist/install-libheif.sh) when distro packages are outdated)

  • librsvg2-bin or librsvg2-tools (SVG conversion helpers)

Use sudo apt install, sudo dnf install, or sudo zypper install with the package names above to pull them in as needed.

We publish the same libheif builds that ship in our Docker images. They include fixes for rotation metadata and newer iOS HEIC variants that are often missing from distribution packages. Advanced users can regenerate them via make build-libheif-*, which calls scripts/dist/build-libheif.sh for each supported base image and architecture before uploading the archives to dl.photoprism.app.

Keep in mind that even if all dependencies are installed, it is possible that you are using a version that is not fully compatible with your pictures, phone, or camera. Our team cannot provide support in these cases if the same issue does not occur with our official Docker images. Details on the packages and package versions we use can be found in the Dockerfiles available in our public project repository.

Configuration

After unpacking the binaries you only need a writable configuration and storage location. The typical workflow is:

  1. Inspect the current settings: photoprism config

  2. Create dedicated directories for runtime data, for example (replace photoprism:photoprism with the user/group that should own the data):

  3. Update /etc/photoprism/defaults.yml so ConfigPath, StoragePath, OriginalsPath, and ImportPath point outside the installation directory.

  4. Optionally place per-instance overrides in <config-path>/options.yml.

  5. Restart the PhotoPrism service (or rerun the CLI command) so the changes take effect.

Run photoprism --help in a terminal to get an overview of the command flags and environment variables available for configuration. Their current values can always be displayed with the photoprism config command.

Precedence

PhotoPrism reads settings in the following order (later entries override earlier ones):

OrderSourceNotes
1Built-in defaultsHard-coded, fall back when nothing else is set.
2/etc/photoprism/defaults.ymlGlobal defaults for all users on the host.
3Environment variables / CLI flagsCombine with service managers or wrappers.
4<config-path>/options.ymlInstance-specific overrides (per user or per deployment).
5Runtime changes in the UIPersisted to options.yml; require a restart when running outside Docker.

If no explicit originals, import and/or assets path has been configured, a list of default directory paths will be searched and the first existing directory will be used for the respective path. To simplify updates, we recommend not storing media, database files, or custom configs in the installation directory itself (for example /opt/photoprism); use another base such as /var/lib/photoprism or a path under the user’s home directory.

All configuration changes—whether made via UI, config files, or environment variables—require a restart to take effect when PhotoPrism runs as a standalone process.

defaults.yml

Packages install a starter /etc/photoprism/defaults.yml. Adjust it with root privileges to set global defaults such as filesystem locations, database options, and network ports. When specifying strings you can use ~ as the current user’s home directory and relative paths starting with ./:

For a list of supported options and their names, see https://docs.photoprism.app/getting-started/config-files/#config-options.

When specifying values, make sure that the data type is the same as in the documentation, e.g. bool values must be either true or false and int values must be whole numbers without any quotes like in the example above.

options.yml

Default config values can be overridden by values specified in an options.yml file as well as with command flags and environment variables. To load values from an existing options.yml file, you can specify its storage path (excluding the filename) by setting the ConfigPath option in your defaults.yml file, using the --config-path command flag, or with the PHOTOPRISM_CONFIG_PATH environment variable.

The values in an options.yml file are not global and can be used to customize individual instances e.g. based on the default values in a defaults.yml file. Both files allow you to set any of the supported options.

Tip: when running PhotoPrism as a systemd service, export environment variables in the service unit or in /etc/default/photoprism. For interactive shells, specify the corresponding flags or prefix commands with variables (for example PHOTOPRISM_DEBUG=true photoprism index). Use the smallest scope that fits your deployment so updates stay manageable.

Documentation

For detailed information on specific features and related resources, see our Knowledge Base, or check the User Guide for help navigating the user interface, a complete list of config options, and other installation methods:

Getting Support

If you need help installing our software at home, you are welcome to post your question in GitHub Discussions or ask in our Community Chat. Common problems can be quickly diagnosed and solved using our Troubleshooting Checklists. Silver, Gold, and Platinum members are also welcome to email us for technical support and advice.

View Support Options ›

+

PhotoPrism® Installation Packages

As an alternative to our Docker images, you can use the packages available at dl.photoprism.app/pkg/linux/ to install PhotoPrism on compatible Linux distributions without building it from source.

These binary installation packages are intended for experienced users and maintainers of third-party integrations only, as they require manual configuration and do not include tested system dependencies. Since we are unable to provide support for custom installations, we recommend using one of our Docker images to run PhotoPrism on a private server or NAS device.

Also note that the minimum required glibc version is 2.35, so for example Ubuntu 22.04 and Debian Bookworm will work, but older Linux distributions may not be compatible.

Usage

Installation Using tar.gz Archives

You can download and install PhotoPrism in /opt/photoprism by running the following commands:

If your server has an ARM-based CPU, please make sure to install arm64.tar.gz instead of amd64.tar.gz when using the commands above. Both are linked to the latest stable release.

Since the packages currently do not include a default configuration, we recommend that you create a defaults.yml in /etc/photoprism next, in which you configure the paths and other settings that you want to use for your instance.

.deb Packages for Ubuntu / Debian Linux

As an alternative to the plain tar.gz archives, that you need to unpack manually, we also offer .deb packages for Debian-based distributions such as Ubuntu Linux. They install PhotoPrism under /opt/photoprism, add a /usr/local/bin/photoprism symlink, create /etc/photoprism/defaults.yml, and pull in the runtime libraries listed in the Dependencies section.

On servers with a 64-bit Intel or AMD CPU, our latest stable release can be installed as follows:

If your server has an ARM-based CPU, such as a Raspberry Pi, use the following commands instead:

Omit --no-install-recommends if you want APT to install MariaDB, Darktable, RawTherapee, ImageMagick, and other recommended extras automatically.

.rpm Packages for Fedora / RHEL / openSUSE

For RPM-based distributions we publish .rpm packages that mirror the layout described above. Install the latest release on x86_64 hardware with:

and on aarch64 (ARM64):

Replace dnf with zypper on openSUSE (use --allow-unsigned-rpm when required). On distributions that do not ship FFmpeg in the base repositories, enable the appropriate multimedia repository (EPEL, RPM Fusion, Packman, …) before installing the dependencies below.

AUR Packages for Arch Linux

Thomas Eizinger additionally maintains AUR packages for installation on Arch Linux. They are based on our tar.gz packages and have a systemd integration so that PhotoPrism can be started and restarted automatically.

Learn more ›

Updates

To update your installation, please stop all running PhotoPrism instances and make sure that there are no media, database, or custom config files in the /opt/photoprism directory. You can then delete its contents with the command sudo rm -rf /opt/photoprism/* and install a new version as shown above.

If you have used a .deb package for installation, you may need to remove the currently installed photoprism package by running sudo dpkg -r photoprism before you can install a new version with sudo apt install ./package.deb or sudo dpkg -i package.deb.

Dependencies

PhotoPrism packages bundle TensorFlow 2.18.0 and, starting with the October 2025 builds, ONNX Runtime 1.22.0 as described in ai/face/README.md. The shared libraries for both frameworks are shipped inside /opt/photoprism/lib, so no additional system packages are needed to switch PHOTOPRISM_FACE_ENGINE to onnx. The binaries still rely on glibc ≥ 2.35 and the standard C/C++ runtime libraries (libstdc++6, libgcc_s1, libgomp1, …) provided by your distribution.

Required Runtime Packages

Install the following packages before running PhotoPrism so that thumbnailing, metadata extraction, and the SQLite fallback database work out of the box:

Distribution familyCommand
Debian / Ubuntusudo apt install libvips42t64 libimage-exiftool-perl ffmpeg sqlite3 tzdata
Use libvips42 or, as a fallback, libvips-dev on older releases.
Fedora / RHEL / Alma / Rockysudo dnf install vips perl-Image-ExifTool ffmpeg sqlite tzdata
openSUSEsudo zypper install vips perl-Image-ExifTool ffmpeg sqlite3 tzdata

These packages pull in the full libvips stack (GLib, libjpeg/libtiff/libwebp, archive/zstd, etc.) that the PhotoPrism binary links against. Run ldd /opt/photoprism/bin/photoprism if you need to diagnose missing libraries on custom distributions.

For extended RAW processing, HEIF/HEIC support, and database scalability we recommend installing:

  • MariaDB or MariaDB Server (external database)

  • Darktable and/or RawTherapee (RAW converters)

  • ImageMagick (CLI utilities)

  • libheif (prefer the up-to-date binaries from dl.photoprism.app/dist/libheif/; install with bash <(curl -s https://raw.githubusercontent.com/photoprism/photoprism/develop/scripts/dist/install-libheif.sh) when distro packages are outdated)

  • librsvg2-bin or librsvg2-tools (SVG conversion helpers)

Use sudo apt install, sudo dnf install, or sudo zypper install with the package names above to pull them in as needed.

We publish the same libheif builds that ship in our Docker images. They include fixes for rotation metadata and newer iOS HEIC variants that are often missing from distribution packages. Advanced users can regenerate them via make build-libheif-*, which calls scripts/dist/build-libheif.sh for each supported base image and architecture before uploading the archives to dl.photoprism.app.

Keep in mind that even if all dependencies are installed, it is possible that you are using a version that is not fully compatible with your pictures, phone, or camera. Our team cannot provide support in these cases if the same issue does not occur with our official Docker images. Details on the packages and package versions we use can be found in the Dockerfiles available in our public project repository.

Configuration

After unpacking the binaries you only need a writable configuration and storage location. The typical workflow is:

  1. Inspect the current settings: photoprism config

  2. Create dedicated directories for runtime data, for example (replace photoprism:photoprism with the user/group that should own the data):

  3. Update /etc/photoprism/defaults.yml (or .yaml) so ConfigPath, StoragePath, OriginalsPath, and ImportPath point outside the installation directory. When the /etc file is missing or empty, PhotoPrism automatically loads <config-path>/defaults.yml, so you may edit the copy under PHOTOPRISM_CONFIG_PATH instead.

  4. Optionally place per-instance overrides in <config-path>/options.yml.

  5. Restart the PhotoPrism service (or rerun the CLI command) so the changes take effect.

Run photoprism --help in a terminal to get an overview of the command flags and environment variables available for configuration. Their current values can always be displayed with the photoprism config command.

Precedence

PhotoPrism reads settings in the following order (later entries override earlier ones):

OrderSourceNotes
1Built-in defaultsHard-coded, fall back when nothing else is set.
2/etc/photoprism/defaults.ymlGlobal defaults for all users on the host; falls back to <config-path>/defaults.yml (respects .yml / .yaml) when missing or empty.
3Environment variables / CLI flagsCombine with service managers or wrappers.
4<config-path>/options.ymlInstance-specific overrides (per user or per deployment).
5Runtime changes in the UIPersisted to options.yml; require a restart when running outside Docker.

If no explicit originals, import and/or assets path has been configured, a list of default directory paths will be searched and the first existing directory will be used for the respective path. To simplify updates, we recommend not storing media, database files, or custom configs in the installation directory itself (for example /opt/photoprism); use another base such as /var/lib/photoprism or a path under the user’s home directory.

All configuration changes—whether made via UI, config files, or environment variables—require a restart to take effect when PhotoPrism runs as a standalone process.

defaults.yml

Packages install a starter /etc/photoprism/defaults.yml. Adjust it with root privileges to set global defaults such as filesystem locations, database options, and network ports. If you delete or leave that file empty, PhotoPrism automatically falls back to <config-path>/defaults.yml, so copying the sample there keeps the same behavior without touching /etc. When specifying strings you can use ~ as the current user’s home directory and relative paths starting with ./:

For a list of supported options and their names, see https://docs.photoprism.app/getting-started/config-files/#config-options.

When specifying values, make sure that the data type is the same as in the documentation, e.g. bool values must be either true or false and int values must be whole numbers without any quotes like in the example above.

options.yml

Default config values can be overridden by values specified in an options.yml file as well as with command flags and environment variables. To load values from an existing options.yml file, you can specify its storage path (excluding the filename) by setting the ConfigPath option in your defaults.yml file, using the --config-path command flag, or with the PHOTOPRISM_CONFIG_PATH environment variable.

The values in an options.yml file are not global and can be used to customize individual instances e.g. based on the default values in a defaults.yml file. Both files allow you to set any of the supported options.

Tip: when running PhotoPrism as a systemd service, export environment variables in the service unit or in /etc/default/photoprism. For interactive shells, specify the corresponding flags or prefix commands with variables (for example PHOTOPRISM_DEBUG=true photoprism index). Use the smallest scope that fits your deployment so updates stay manageable.

Documentation

For detailed information on specific features and related resources, see our Knowledge Base, or check the User Guide for help navigating the user interface, a complete list of config options, and other installation methods:

Getting Support

If you need help installing our software at home, you are welcome to post your question in GitHub Discussions or ask in our Community Chat. Common problems can be quickly diagnosed and solved using our Troubleshooting Checklists. Silver, Gold, and Platinum members are also welcome to email us for technical support and advice.

View Support Options ›

\ No newline at end of file diff --git a/setup/pkg/linux/README.md b/setup/pkg/linux/README.md index 94fba05d6..fc3fcb0c2 100644 --- a/setup/pkg/linux/README.md +++ b/setup/pkg/linux/README.md @@ -114,7 +114,7 @@ After unpacking the binaries you only need a writable configuration and storage sudo mkdir -p /var/lib/photoprism/{config,storage} sudo chown -R photoprism:photoprism /var/lib/photoprism ``` -3. Update `/etc/photoprism/defaults.yml` so `ConfigPath`, `StoragePath`, `OriginalsPath`, and `ImportPath` point outside the installation directory. +3. Update `/etc/photoprism/defaults.yml` (or `.yaml`) so `ConfigPath`, `StoragePath`, `OriginalsPath`, and `ImportPath` point outside the installation directory. When the `/etc` file is missing or empty, PhotoPrism automatically loads `/defaults.yml`, so you may edit the copy under `PHOTOPRISM_CONFIG_PATH` instead. 4. Optionally place per-instance overrides in `/options.yml`. 5. Restart the PhotoPrism service (or rerun the CLI command) so the changes take effect. @@ -124,13 +124,13 @@ Run `photoprism --help` in a terminal to get an [overview of the command flags a PhotoPrism reads settings in the following order (later entries override earlier ones): -| Order | Source | Notes | -|-------|-----------------------------------|----------------------------------------------------------------------------| -| 1 | Built-in defaults | Hard-coded, fall back when nothing else is set. | -| 2 | `/etc/photoprism/defaults.yml` | Global defaults for all users on the host. | -| 3 | Environment variables / CLI flags | Combine with service managers or wrappers. | -| 4 | `/options.yml` | Instance-specific overrides (per user or per deployment). | -| 5 | Runtime changes in the UI | Persisted to `options.yml`; require a restart when running outside Docker. | +| Order | Source | Notes | +|-------|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| 1 | Built-in defaults | Hard-coded, fall back when nothing else is set. | +| 2 | `/etc/photoprism/defaults.yml` | Global defaults for all users on the host; falls back to `/defaults.yml` (respects `.yml` / `.yaml`) when missing or empty. | +| 3 | Environment variables / CLI flags | Combine with service managers or wrappers. | +| 4 | `/options.yml` | Instance-specific overrides (per user or per deployment). | +| 5 | Runtime changes in the UI | Persisted to `options.yml`; require a restart when running outside Docker. | If no explicit *originals*, *import* and/or *assets* path has been configured, a list of [default directory paths](https://github.com/photoprism/photoprism/blob/develop/pkg/fs/directories.go) will be searched and the first existing directory will be used for the respective path. To simplify [updates](#updates), we recommend **not** storing media, database files, or custom configs in the installation directory itself (for example `/opt/photoprism`); use another base such as `/var/lib/photoprism` or a path under the user’s home directory. @@ -138,7 +138,7 @@ All configuration changes—whether made [via UI](https://docs.photoprism.app/us ### `defaults.yml` -Packages install a starter `/etc/photoprism/defaults.yml`. Adjust it with root privileges to set global defaults such as filesystem locations, database options, and network ports. When specifying strings you can use `~` as the current user’s home directory and relative paths starting with `./`: +Packages install a starter `/etc/photoprism/defaults.yml`. Adjust it with root privileges to set global defaults such as filesystem locations, database options, and network ports. If you delete or leave that file empty, PhotoPrism automatically falls back to `/defaults.yml`, so copying the sample there keeps the same behavior without touching `/etc`. When specifying strings you can use `~` as the current user’s home directory and relative paths starting with `./`: ```yaml ConfigPath: "~/.config/photoprism"