johanels/photoprism
1
0
Fork 0
mirror of https://github.com/photoprism/photoprism.git synced 2025-12-11 16:24:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

Config: Add fallback to load defaults from "config/defaults.yml" #5325

Browse Source 
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 <michael@photoprism.app>
This commit is contained in:
Michael Mayer
2025-11-16 09:06:12 +01:00
parent 217c5a44e3
commit 315b49c1e6
4 changed files with 44 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
internal/config/README.md
View File

@@ -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 <flag>` 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.

14
internal/config/config_storage.go
View File

@@ -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)
}

6
setup/pkg/linux/README.html
View File

File diff suppressed because one or more lines are too long

18
setup/pkg/linux/README.md
View File

@@ -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 `<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.
@@ -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 | `<config-path>/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 `<config-path>/defaults.yml` (respects `.yml` / `.yaml`) when missing or empty. |
| 3 | Environment variables / CLI flags | Combine with service managers or wrappers. |
| 4 | `<config-path>/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 `<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 `./`:
```yaml
ConfigPath: "~/.config/photoprism"