# Move to a new server

Source: https://frameleaf.app/docs/admin/move-to-a-new-server/

Moving to new hardware is safe and resumable, and you finish with a checksum-verified report before you retire anything. There are two ways to do it:

- **Move the whole server.** Copy your files and restore a database backup on the new machine. See [Move the whole server](#move-the-whole-server) below.
- **Move one person's library** to a different, already running server. That's what most of this page covers.

Only changing drives inside the same server? Use Manager's **Storage** page instead. See [Move data to another drive](https://frameleaf.app/docs/admin/move-data-to-another-drive/).

If you use Cloud Backup, you can also move the whole server from a complete independent export, then recover it on the new server without Cloud access. Keep its recovery file, media, configuration and keys private. See [Export and recover without Cloud access](https://frameleaf.app/docs/admin/server-commands/#export-and-recover-without-cloud-access). The database dump in the export is restored as a separate step.

A library move uses the `migrate` command of the Frameleaf command-line tool. It runs on a computer you control, copies everything over the API, and ends with an audit you review before you retire the old server.

Your old server stays exactly as it is: the move never deletes anything there, and you decide when to retire it. The web app doesn't run migrations or ask for API keys.

## Move the whole server

A database backup alone doesn't move a library: the new server needs your photos and videos too.

**With Frameleaf Manager**

1. On the old server, open **Backups** in Manager and choose **Make one now**. Then **Export key** beside **Recovery key**, and in **Manager settings** choose **Export** beside **Configuration export**. Stop Frameleaf from **Services** so nothing changes while you copy.
2. Copy the photos folder, the thumbnails folder if it's on a drive of its own, and Manager's backups folder to the new server. Keep the photos at the same folder paths as on the old server: the restore reconnects files where the database expects them and doesn't copy any media itself.
3. Install Manager on the new server and create its administrator. See [Install with Frameleaf Manager](https://frameleaf.app/docs/start/install/).
4. On **Choose how to begin**, under **Restore a backup**, select **Choose a backup**, enter your **Recovery key** and select **Unlock backups**. Then pick the recovery point and follow [Restore a Manager backup](https://frameleaf.app/docs/admin/backup-and-restore/#restore-a-manager-backup). The review lists each folder the library expects, so you can see that your photos are where they should be before anything is restored.
5. Open Frameleaf, sign in and check a few albums, originals and videos before you retire the old server.

**With Docker Compose**

Set up the new installation, move the storage folders into its `UPLOAD_LOCATION` and choose **Restore from a backup** on the welcome page. See [Restore on a fresh installation](https://frameleaf.app/docs/admin/backup-and-restore/#on-a-fresh-installation). If the media folder ends up at a different path inside the container, see [Change the media location](#change-the-media-location) below.

Either way, keep the old server as it is until the new one has a backup of its own.

## How a library move works

1. **Preflight** checks both connections, the API key permissions and the owner on each side. It changes nothing.
2. **Dry run** lists what would move and what the new server already has. It writes nothing.
3. **Run** copies originals, then albums (with their collections), tags, stacks and people. Every finished item is saved to a local ledger file, so an interrupted run resumes where it stopped.
4. **Retry** tries failed originals again, adds them to their albums and tags, and reattaches names to faces.
5. **Verify** checks every original on the new server by checksum, without contacting the old one, and writes an audit report.

## Before you start

Move one person at a time. You need an API key **for that person on both servers**. A key can only read and write its own account's library, so an administrator's key would copy the photos into the administrator's account.

Sign in as the person on each server, open **Settings**, then **Your sign-in & privacy**, then **API keys**, and create a key with these permissions (or `all`):

| Server | Required | Optional |
| --- | --- | --- |
| Old | `asset.read`, `asset.download`, `album.read`, `tag.read` | `stack.read`, `person.read` |
| New | `asset.upload`, `asset.update`, `album.create`, `albumAsset.create`, `tag.create`, `tag.asset` | `stack.create`, `person.create`, `person.reassign`, `face.read` |

Without the optional permissions, stacks and people are skipped and everything else still moves. If the account doesn't exist on the new server yet, create it first.

## 1. Build the tool

From a checkout of the [Frameleaf source](https://github.com/Frameleaf/frameleaf-app), on the computer that will run the move:

```bash
pnpm install --frozen-lockfile
pnpm --filter @frameleaf/sdk build
pnpm --filter @frameleaf/cli build
```

The computer needs network access to both servers and only a little free disk: each original is streamed to a temporary folder next to the ledger and removed as soon as it's uploaded.

## 2. Enter the addresses and keys

Type each key when the terminal waits for it. Nothing is shown as you type, and the key stays out of your shell history. The tool also has `--from-key` and `--to-key` options, but a key typed on the command line is saved in your shell history, so use the variables.

```bash
export FRAMELEAF_FROM_URL=https://old-server.example/api
export FRAMELEAF_TO_URL=https://new-server.example/api
read -rs FRAMELEAF_FROM_KEY && export FRAMELEAF_FROM_KEY
read -rs FRAMELEAF_TO_KEY && export FRAMELEAF_TO_KEY
```

## 3. Preflight and dry run

```bash
node packages/cli/dist/index.js migrate --preflight --ledger ./library-move.sqlite
node packages/cli/dist/index.js migrate --dry-run --ledger ./library-move.sqlite
```

Preflight stops on any missing required permission and warns if the two accounts have different email addresses (everything ends up owned by the new server's account). It doesn't create a ledger. If an existing ledger was made for a different pair of servers, use a different `--ledger` path.

The dry run fills the ledger with what's on the old server and asks the new one which originals it already has. Its report is marked as a dry run and never shows a pass.

## 4. Run the move

```bash
node packages/cli/dist/index.js migrate --ledger ./library-move.sqlite --serve
```

`--serve` adds a progress page at `http://127.0.0.1:2285` where you can pause, resume or stop. Closing the page doesn't stop the move.

If the run stops for any reason (Ctrl+C, a reboot, a dropped connection), just run **the same command** again. The ledger skips everything already done. Keep the ledger file until you've retired the old server.

Albums, tags and stacks are only marked complete once every one of their photos is on the new server. If an original failed, its albums stay pending until it arrives.

A few options change what a run does:

| Option | What it does |
| --- | --- |
| `--rescan` | On a ledger you've already used, look at the old server again and copy photos added since the last run, without making duplicates |
| `--include-trashed` | Also move items in the Trash |
| `--no-faces` | Skip people and faces |
| `--concurrency <number>` | How many originals to move at once |
| `--port <number>` | The port for the progress page, `2285` unless you change it |

## 5. Retry failed items

Fix the cause first (a damaged or missing original on the old server, a timeout), then:

```bash
node packages/cli/dist/index.js migrate --ledger ./library-move.sqlite --retry-failed
```

:::tip[Best face results]
Run the move once with `--no-faces`, wait for the new server to finish face detection, then run `--retry-failed` to attach names.
:::

## 6. Verify

```bash
node packages/cli/dist/index.js migrate --verify --ledger ./library-move.sqlite
```

This needs only the `FRAMELEAF_TO_*` variables. It rechecks every original in the ledger against the new server and writes `library-move.sqlite.audit.json`, and refuses a server other than the one the ledger was written for. Photos added to the old server after the run aren't included; run step 4 again with `--rescan` to pick them up, then verify.

A ledger used only for dry runs never verifies as a pass, and `--verify` takes no other options. The exit status is `0` only for a pass, `2` for anything else and `1` for an error, so you can script it.

## Review the audit report

On the new server, open **Settings**, then **Storage & originals**, then **Move or export**, and choose **Prepare migration checklist**. Continue through **Source** and **Preflight** to **Review**, choose **Open audit report** and select the audit file. The report stays private: it's read in your browser only, never uploaded or saved, and closing it discards it.

| Section | What it shows |
| --- | --- |
| Verdict | **Pass** only when every original was checked, none is missing or failed, and every one was verified. **Incomplete**, **Audit incomplete** (the audit was stopped) and **Dry run** are never a pass |
| Owners | The account copied from and the account that owns everything on the new server |
| Originals | **Transferred** (the ledger records it on the new server) and **Verified by checksum** (found there by this audit). Only verified originals count |
| Albums | Albums complete out of the total, top level or inside a collection |
| Tags, people, stacks | Tags assigned, names attached to faces and stacks recreated, each out of the total |
| Physical references | New uploads, originals that matched a file the new server already had, and Live Photo pairs linked |
| Unresolved items | Every original, album, tag, stack or person still outstanding, with its reason. Filter by type or name |

The page only opens a clean, current audit report: one with no credentials or file paths from either computer, and counts that agree with each other and the verdict. If it's refused, run the verify command again for a fresh file.

## Retire the old server

Retire it only when:

- the latest report shows **Pass**
- every unresolved item is fixed or accepted
- you have a backup of the new server
- you've kept the ledger file and the final report

Album sharing, activity, comments and anything owned by another account aren't moved. Thumbnails, faces, smart search and places are rebuilt by the new server's own jobs.

:::caution[Evidence, not certification]
The report shows exactly what reached the new server in this run. It's a record of your library, not a certificate for a server version or compatibility.
:::

## Change the media location

If you move a whole server and the media folder is mounted at a different path inside the container than before, the database still holds the old paths. The `change-media-location` command rewrites them:

```bash
docker exec -it frameleaf_server frameleaf-admin change-media-location
```

It asks for the previous and the new value of `FRAMELEAF_MEDIA_LOCATION` (for example `/data` and `/my-data`), shows the change and asks you to confirm. Then set `FRAMELEAF_MEDIA_LOCATION` to the new value and restart. Back up the database first. See [Server commands](https://frameleaf.app/docs/admin/server-commands/).
