Server commands

The Frameleaf server image, ghcr.io/frameleaf/frameleaf-server, includes an administration tool called frameleaf-admin. Use it when you can’t, or would rather not, use the web app: to get back in after losing the admin password, to turn maintenance mode on or off, or to recover a server.

How to run a command

From the folder with your docker-compose.yml:

docker compose exec immich-server frameleaf-admin <command>

For commands that ask questions, add -it after exec. Or open a shell in the container and run commands from there:

docker compose exec -it immich-server bash
frameleaf-admin <command>

The immich-server service name stays the same whatever the container is called. docker exec -it frameleaf_server frameleaf-admin <command> works too, if your container has the default name.

Commands

Command	What it does
`help`	Show help
`reset-admin-password`	Reset the administrator’s password
`setup-code`	Print the setup code of a server that has no administrator yet
`disable-password-login`	Turn off password sign-in
`enable-password-login`	Turn on password sign-in
`disable-oauth-login`	Turn off sign-in with your own provider (OAuth)
`enable-oauth-login`	Turn on sign-in with your own provider (OAuth)
`enable-maintenance-mode`	Turn on maintenance mode, or get a new sign-in address for it
`disable-maintenance-mode`	Turn off maintenance mode
`list-users`	List the accounts on the server
`grant-admin`	Make an account an administrator, by email
`revoke-admin`	Remove administrator rights from an account, by email
`version`	Print the Frameleaf version
`change-media-location`	Rewrite file paths in the database after the media folder moves
`schema-check`	Check database migrations and look for schema drift
`cloud-backup restore`	Restore the server from its cloud backup bucket, without the web app
`buddy-backup export` and `buddy-backup recover`	Export or decrypt a Buddy backup vault offline. See Buddy backup
`fork-schema`, `fork-schema-cutover` and `fork-handoff`	Compatibility and handoff steps for moving between Frameleaf and the official Immich server. See Going back to Immich

Examples

Reset the admin password

$ frameleaf-admin reset-admin-password
Found Admin:
- ID=e65e6f88-2a30-4dbe-8dd9-1885f4889b53
- OAuth ID=
- [email protected]
- Name=Frameleaf Admin
? Please choose a new password (optional) frameleaf-is-cool
? Invalidate existing sessions? Yes
The admin password has been updated.

Get a new server’s setup code

Until a server has an administrator, it prints a setup code on its console. If that output is gone, print it again:

docker compose exec immich-server frameleaf-admin setup-code

The code changes every time the server starts. Add --plain to print only the code, for scripts. Once the server has an administrator, there’s no code and the command says so.

$ frameleaf-admin disable-password-login
Password login has been disabled.

$ frameleaf-admin enable-password-login
Password login has been enabled.

$ frameleaf-admin enable-oauth-login
OAuth login has been enabled.

$ frameleaf-admin disable-oauth-login
OAuth login has been disabled.

If a sign-in provider change locks everyone out, turn password sign-in back on with enable-password-login.

Maintenance mode

$ frameleaf-admin enable-maintenance-mode
Maintenance mode has been enabled.

Log in using the following URL:
https://photos.example.com/maintenance?token=<token>

$ frameleaf-admin disable-maintenance-mode
Maintenance mode has been disabled.

Accounts and administrators

$ frameleaf-admin list-users
[
  {
    id: 'e65e6f88-2a30-4dbe-8dd9-1885f4889b53',
    email: '[email protected]',
    name: 'Frameleaf Admin',
    storageLabel: 'admin',
    isAdmin: true,
    ...
  }
]

$ frameleaf-admin grant-admin
? Please enter the user email:  [email protected]
Admin access has been granted to [email protected]

$ frameleaf-admin revoke-admin
? Please enter the user email:  [email protected]
Admin access has been revoked from [email protected]

Change the media location

If the media folder is mounted at a different path inside the container than before, for example after moving to new hardware, the database still points at the old paths. Back up the database first, then:

$ frameleaf-admin change-media-location
? Enter the previous value of FRAMELEAF_MEDIA_LOCATION: /data
? Enter the new value of FRAMELEAF_MEDIA_LOCATION: /my-data
...
  Previous value: /data
  Current value:  /my-data

  Changing database paths from "/data/*" to "/my-data/*"

? Do you want to proceed? [Y/n] y

Database file paths updated successfully!

Then set FRAMELEAF_MEDIA_LOCATION to the new value and restart.

Check the database schema

$ frameleaf-admin schema-check
Migrations are up to date

No schema drift detected

Restore from a cloud backup bucket

If the server is lost, cloud-backup restore brings back its files and database from its Cloud backup bucket on a fresh installation, without the web app. Secrets come from environment variables, never the command line, so they stay out of your shell history.

read -rs FRAMELEAF_BACKUP_SECRET_ACCESS_KEY && export FRAMELEAF_BACKUP_SECRET_ACCESS_KEY
frameleaf-admin cloud-backup restore \
  --bucket <bucket> \
  --endpoint https://s3.eu-central-2.wasabisys.com \
  --access-key-id <access key ID> \
  --key-file /path/to/backup-key-file

Option	What it’s for
`--bucket <name>`	The backup bucket. Required
`--endpoint <url>`	The storage address. Required
`--access-key-id <id>`	The access key ID. Required. Its secret is read from `FRAMELEAF_BACKUP_SECRET_ACCESS_KEY`
`--region <region>`	The region. Read from the storage address if you leave it out
`--key-file <path>`	The backup key file, or a file holding the recovery code
`--escrow-file <path>`	Instead of `--key-file`: a key copy from your Frameleaf account. Its passphrase is read from `FRAMELEAF_BACKUP_ESCROW_PASSPHRASE`
`--manifest <key>`	Which backup to restore, as `m/<time>.json.gz`. The newest if you leave it out
`--scope <scope>`	`library` (default): files in place and the database dump. `files`: files into a restore folder. `database`: the dump only
`--restore-database`	Also restore the database from the dump, replacing the current one

Give the key with either --key-file or --escrow-file, not both. Without --restore-database, the database dump is left in the backups folder for you to restore from Administration, then Maintenance (see Backup and restore). After a database restore, start the server and set up cloud backup again.

Going back to the official server

There’s no single command to downgrade to the official Immich server; an older schema-revert-to-upstream command was removed because it wasn’t safe. Follow Going back to Immich, which uses the fork-schema, fork-schema-cutover and fork-handoff commands.