# Accounts, passwords and where they're kept

Source: https://frameleaf.app/docs/admin/credentials/

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.

:::danger[Read before changing anything]
Most of these values are wired together. If you change a password in one place and not the others, Frameleaf can't reach its database and stops working until it's put back. Before you edit anything on this page:

- Take a database backup and keep it somewhere safe ([Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/)).
- Change only one thing at a time, and write down the old value first.
- Never post these files, passwords or `docker inspect` output in a forum or bug report.
:::

## At a glance

| 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](https://frameleaf.app/docs/cloud/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` |

## Frameleaf server

### Administrator account

The first account, created during [setup](https://frameleaf.app/docs/start/first-steps/#your-account), 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](https://frameleaf.app/docs/cloud/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:

```bash
docker exec -it frameleaf_server frameleaf-admin reset-admin-password
```

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

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

[Server commands](https://frameleaf.app/docs/admin/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.

:::caution
Don't edit the `user` table directly to change a password or an email address. Use **Settings**, then **Users**, or `frameleaf-admin`. A hand-edited row can lock the account out or break sign-in for everyone.
:::

### Frameleaf Manager administrator

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.

:::danger
There's no command to reset a lost Manager password. Keep it in a password manager, and keep your exported **Configuration export** and **recovery key** somewhere private ([Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/)). Don't edit or delete `manager.sqlite`: it also holds your installation, its database password and backup state, so a damaged file can leave Manager unable to manage or restore your library.
:::

### Manager's state folder

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:

```bash
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](https://frameleaf.app/docs/admin/manager/#containers) page in Manager instead (**Advanced container settings** during setup). It also shows everything Manager writes into each container.

## Database

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

### Manager installations

| 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:

```bash
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:

```bash
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.

:::danger[Don't change the Manager database password]
Manager has no option to change the database password, and editing `database-password` won't do it. PostgreSQL only reads that file when it first creates the database. After that, the password lives inside PostgreSQL. If you edit the file, the server tries the new password, PostgreSQL still expects the old one, and Frameleaf stops with a database connection error.

Likewise, don't run `ALTER ROLE frameleaf PASSWORD …`. Manager would keep handing out the old password, and its backups, restores and updates would fail.

Manager also writes this file again from its own copy whenever it rebuilds the stack, for example on an update, so hand edits don't last. If the file was changed by mistake, put the old value back, then restart the stack from **Services**.
:::

### Manual installations

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:

```bash
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](https://frameleaf.app/docs/admin/environment-variables/)).

:::caution[Changing the database password on a manual installation]
Editing `DB_PASSWORD` in `.env` on its own doesn't change the database password, for the same reason as above: PostgreSQL only uses it when it first creates the database. Frameleaf then can't connect.

To change it safely:

1. Take a database backup.
2. Change the password inside PostgreSQL:

   ```bash
   docker exec -it frameleaf_postgres psql -U postgres -d frameleaf -c "ALTER ROLE postgres PASSWORD 'new-password';"
   ```

3. Put the same password in `DB_PASSWORD` in `.env`.
4. Restart the stack with `docker compose up -d --force-recreate`.

A password with a single quote (`'`) needs it doubled in the SQL command, so letters and numbers are simplest. If you use `DB_URL` instead of `DB_PASSWORD`, change the password inside the URL too, and percent-encode symbols such as `@`, `:` and `/`. Don't change `DB_USERNAME` or `DB_DATABASE_NAME` on an existing installation. That points Frameleaf at a database that doesn't exist, rather than renaming yours.
:::

### Changes inside the database

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](https://github.com/Frameleaf/frameleaf-app/discussions) first, and take a backup before you try anything.

## Related

- [Database storage and recovery](https://frameleaf.app/docs/admin/database/)
- [Server commands](https://frameleaf.app/docs/admin/server-commands/)
- [Environment variables](https://frameleaf.app/docs/admin/environment-variables/#database)
- [Backup and restore](https://frameleaf.app/docs/admin/backup-and-restore/)
