Skip to content

Accounts, passwords and where they're kept

This page is for advanced users who want to connect to the database directly, recover access, or understand what an installation keeps on disk. You don’t need any of it for everyday use.

What User name Password set by Where it’s kept
Frameleaf server administrator The email you entered during setup You, during setup (at least 8 characters) Hashed in the database. It can’t be read back.
Frameleaf Manager administrator The name you entered when you set up Manager You, when you set up Manager (at least 14 characters) Hashed in manager.sqlite in Manager’s state folder. It can’t be read back.
Frameleaf account (optional) Your Frameleaf account email You, at frameleaf.cloud or during setup (at least 8 characters) Kept by Frameleaf Cloud. See Your Frameleaf account.
Database, Manager installation frameleaf Manager, at random database-password in Manager’s state folder
Database, manual installation DB_USERNAME in .env (default postgres) You, or the install script at random DB_PASSWORD in .env

The first account, created during setup, is the administrator. It’s always a local account on your server, so it works whether or not the server is linked to a Frameleaf account, and there’s no setup code. Its user name is the email address you entered, and you chose its password, at least 8 characters. Frameleaf keeps only a one-way hash of the password in the database, so nobody can look it up. If it’s lost, you have to reset it.

A Frameleaf account is separate. Linking one during setup or later adds remote access and other Cloud features, but it doesn’t replace the local administrator’s password. See Your Frameleaf account.

To reset it, run this in the server container. It asks for a new password, or creates one for you if you leave it blank:

Terminal window
docker exec -it frameleaf_server frameleaf-admin reset-admin-password

On a Manager installation the container has a different name. Find it with:

Terminal window
docker ps --format '{{.Names}}' --filter label=com.docker.compose.service=frameleaf-server

Server commands has the rest of the frameleaf-admin commands, including turning password sign-in back on if a sign-in provider change locks everyone out.

Manager has its own administrator, separate from your photo library account. You chose its name and password (at least 14 characters) the first time you opened Manager. Manager keeps only a hash of the password, in manager.sqlite in its state folder.

To change the name or password, open Manager settings and confirm your current password. Saving signs out every other Manager session.

With the launcher, the state folder is manager inside the parent folder you gave it, or the second folder you gave it if you named every folder yourself. On TrueNAS it’s the MANAGER_DATA folder in your YAML. On Unraid it’s the template’s State path, /mnt/user/appdata/frameleaf-manager unless you changed it. On HexOS it’s frameleaf/manager in your Applications (performance) location. To print it:

Terminal window
docker exec frameleaf-manager node -p 'process.env.MANAGER_DATA'

Use your container’s name if it isn’t frameleaf-manager. The folder is readable only by its owner, so reading files in it on the host usually needs sudo. It contains:

File What it is
manager.sqlite Manager’s settings, administrator, installation details and operation history
stack/database-password The database password, used by the server and PostgreSQL
stack/manager-token The private key the server uses to talk to Manager
stack/ (other files) The Compose stack Manager generates for your library

Manager rewrites the files in stack/ on every update, restore and library move, so hand edits to them don’t last. To add environment variables, folders or limits, use the Containers page in Manager instead (Advanced container settings during setup). It also shows everything Manager writes into each container.

Frameleaf uses PostgreSQL. It’s only reachable inside the stack’s private network on port 5432. It isn’t published to your home network.

Setting Value
User name frameleaf
Database frameleaf
Password Random, 64 characters, created by Manager
Host and port database:5432, inside the stack only

Manager creates a new random password whenever it sets up or restores a library. It never puts the password in the containers’ environment, in docker inspect output or in the Compose file. Instead the server and PostgreSQL both read it from the database-password file, mounted read-only at /run/frameleaf/database-password.

To read the password:

Terminal window
sudo cat "$(docker exec frameleaf-manager node -p 'process.env.MANAGER_DATA')/stack/database-password"

To open a SQL prompt without copying the password anywhere, use the database container:

Terminal window
db=$(docker ps --format '{{.Names}}' --filter label=com.docker.compose.service=database --filter label=app.frameleaf.manager)
docker exec -it "$db" psql -U frameleaf -d frameleaf

If more than one library runs on the host, that finds more than one container. Run docker ps and choose the right one.

A manual (Docker Compose) installation reads its database settings from .env next to docker-compose.yml:

Setting .env key Default
User name DB_USERNAME postgres
Database DB_DATABASE_NAME frameleaf
Password DB_PASSWORD postgres in example.env. The install script replaces it with a random 24-character password.
Container frameleaf_postgres

To open a SQL prompt:

Terminal window
docker exec -it frameleaf_postgres psql -U postgres -d frameleaf

Use your DB_USERNAME and DB_DATABASE_NAME if you changed them. To keep the password out of .env, set DB_PASSWORD_FILE to a file instead (Environment variables).

Look, but don’t touch. Reading tables with psql is safe. Writing to them isn’t supported: Frameleaf keeps caches, search indexes and background work that expect the database to change only through Frameleaf. A direct UPDATE or DELETE can hide photos, break albums or start jobs over, and an upgrade can fail on data it doesn’t expect. If you need to fix something, ask in GitHub Discussions first, and take a backup before you try anything.