Using environment variables with PhotoStructure

Using environment variables with PhotoStructure

You can use environment variables to configure PhotoStructure’s settings. The defaults.env file describes all of PhotoStructure’s settings, and how to change each with an environment variable. This file will also be found in your root app directory (from version 0.9.0 and later) if you’re using a PhotoStructure for Servers edition.

  • You can edit your settings.toml files and set environment variables.

  • Environment variables override any values found in settings.toml, unless you leave the value blank. A blank counts as “not set” wherever you put it.

  • PhotoStructure also reads settings from .env files named by your PS_ENV_FILE environment variable. See below for details.

⚠️ Environment variable overrides and settings.toml values don’t mix

PhotoStructure does not write environment variables overrides to your settings.toml files.

This is actually by design: previous versions of PhotoStructure didn’t discriminate between settings.toml values and environment variable overrides. As an example, if you had set PS_LOG_LEVEL=debug and then saved your settings via the web UI, that debug value would get persisted and become the new default log level.

This behavior was surprising and confusing to most beta users. Thanks to the principle of least astonishment, we decided that this was a “bug,” not a “feature,” and changed PhotoStructure to keep environment variable overrides separated from values stored in the settings.toml files.

🚫 Blank values are ignored

A blank value (empty, or nothing but whitespace) means the same thing as no value at all, wherever you set it: an environment variable, a line in settings.toml, a command-line argument, or the settings page. PhotoStructure skips the blank, and another configured value or the built-in default remains in effect.

A blank is almost always an accident: a docker-compose.yml line that lost its value, or an export PS_LOG_LEVEL= that never got finished. The setting looks configured but does nothing, so PhotoStructure’s settings health checks call it out. For an environment variable, the report names the variable. For a settings.toml line, the warning reads:

Blank value for “logLevel” is ignored; the line has no effect. Remove it or give it a value.

A blank line in a settings.toml also clears whatever that file had saved for that setting, because PhotoStructure reads each file as the complete record of what you saved there.

Earlier versions honored a blank value for text settings, silently overriding settings.toml with an empty string.

A few settings treat a blank as an off switch

A blank means “ignore this” unless the setting’s own description says otherwise. keywordDelimiters is one of the exceptions: an empty string is how you stop PhotoStructure from splitting keywords on commas. Every setting that honors a blank says so in its description, both in your settings.toml files and in defaults.env, so read the description rather than guessing.

🥇 Setting precedence

When the same setting is configured in several places, the first value in this list wins:

  1. test overrides (only used by PhotoStructure’s own test suite)
  2. command-line arguments
  3. environment variables
  4. settings changed in the app while it’s running
  5. your settings.toml files
  6. the built-in default

✓ Boolean settings

Boolean settings interpret either true or 1 as true, and false or 0 for false.

For example:

PS_VERIFY_FILE_COPIES=true

🔄 Converting between settings names and environment variable names

To avoid name-colliding with other software, all PhotoStructure environment variables are prefixed with PS_ and converted to UPPER_SNAKE_CASE.

Examples

  • The PS_LOG_LEVEL environment variable overrides the logLevel setting.

  • The PS_MIN_DISK_FREE_GB environment variable overrides the minDiskFreeGb setting.

⚠️ Caution: upgrades to your environment variables are not automatic

When you upgrade to a new version of PhotoStructure, your prior settings.toml files are automatically migrated to contain the settings (and defaults) of the new version, while retaining your custom configurations.

We cannot do this for environment variables because we do not know where your environment variables are coming from. They can be set in many different ways.

If you use environment variables, you must review our release notes and make suitable settings changes when you upgrade. We mark any settings that are deleted, renamed, or have changed semantics.

It also might be helpful to look at differences between version tags on github.

⚙️ How to set environment variables per OS

PhotoStructure for Desktops on macOS

If you’re using PhotoStructure for Desktops on macOS, you can set environment variables with launchctl setenv.

To disable video transcoding, for example, open a terminal and run:

launchctl setenv PS_TRANSCODE_VIDEOS false

To get the current value, use launchctl getenv:

launchctl getenv PS_TRANSCODE_VIDEOS

To unset (and use PhotoStructure’s default), use launchctl unsetenv:

launchctl unsetenv PS_TRANSCODE_VIDEOS

PhotoStructure for Servers on Linux and macOS

Add environment variables to the relevant RC script for your shell. If you’re using bash, that’s ~/.profile:

export PS_LOG_LEVEL=info

PhotoStructure on Windows

  1. Hit the Windows key, and type “environment”,
  2. select “Edit the system environment variables” control panel,
  3. click the Environment Variables... button in the bottom right, and
  4. click the top New... button. Pick the top New... button if you’re using PhotoStructure for Desktops. If you’re running PhotoStructure as a system service, pick the bottom New... button.

Docker

With docker, use --env or --env-file :

docker run --name photostructure --env PS_LOG_LEVEL=info ...

With Docker Compose, use the environment or env_file configuration option

...
    environment:
      - "PS_LOG_LEVEL=info"
...

📄 Support for .env files

Version 2023 and later added support for reading .env files via the PS_ENV_FILE environment variable.

On startup, PhotoStructure will attempt to read .env files from the following paths, in this order:

  1. /.psenv
  2. $HOME/.psenv
  3. $PS_ENV_FILE
  4. $PS_ENV
  5. $PSENV

Files that are missing or unreadable are skipped. $PS_ENV_FILE, $PS_ENV, and $PSENV can each name more than one file, separated the same way as your PATH: a colon on Linux and macOS, a semicolon on Windows.

If the same key appears in more than one .env file, the last one wins.

.env file format

PhotoStructure reads standard .env-formatted files.

  • Any # outside of quotes is considered the start of a comment.
  • Values should be wrapped in double-quotes.
  • Newlines can be encoded as “\n”, or as actual newlines in the text file.
  • Save your .env as UTF-8. A byte-order mark is stripped if your editor adds one.
# This is a comment.
PS_LIBRARY_DIR="/path/to your/library"
PS_LOG_LEVEL="info"
# You can add backslash-n as a newline character like this
MULTI_LINE0="first line\nsecond line"
# Or if you prefer (but this is not valid shell):
MULTI_LINE1="this is
also a valid
multi line value"

Note that parameter expansion or other shell constructs, like conditionals, are not supported.

See also