> For the complete documentation index, see [llms.txt](https://docs.fylr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fylr.io/for-system-administrators/inspect/migration.md). # Migration The migration using the `fylr backup` and `fylr restore` commands can also be performed in the inspect page for migrations (open `/inspect/migration/` in the browser). This provides a graphical overview to run these commands. The source instance for the backup can be any **easydb5** or **fylr** instance, even the current **fylr** instance. The same is true for the target instance of the restore, this can be the same **fylr** instance. The following example shows how a backup with the name *"example"* would be migrated from server *""* to server *""*. The backup and restore processes are performed in the background. They run on the server and are independent of the browser window. The progress can be checked by opening the status page of a backup / restore process (see below). ## Backup This uses `fylr backup` to create a backup on the **fylr** instance. Not all parameters can be set here. Some parameters are automatically set with a useful default. See also: [Backup Parameters](/for-system-administrators/migration/backup.md#parameters) ### Parameter settings #### Name of backup * choose a name to identify the backup * This sets `--dir example/` #### URL of server * URL of the source server **without** API base endpoint * This sets `--server 'http://example.fylr.xyz/api/v1/'` #### Login * Username in the source instance * This sets `--login root` #### Password * Password in the source instance * This sets `--password '12345'` #### Backup chunk size * Select the batch size for GET requests * Choose between: `10`, `25`, `50`, `100`, `500`, `1000` * This sets `--chunk` #### Include object history * If set, the backup will include all versions of an object * With this option, the full changelog of an object will be available after restore * This option is enabled by default * This sets `--all-versions true` #### Include soft-deleted objects {% hint style="info" %} This parameter is available in fylr from version **6.33.0**. {% endhint %} * If set, objects that are soft-deleted in the source are included in the backup as top-level entries (in their soft-deleted state) * Links pointing at soft-deleted targets are always written to the backup as a `lookup:_id` wrapper carrying `_latest_version_deleted_at`; this option only controls whether the target object itself rides along * Pair with the restore-side *"Include links to soft-deleted objects"* for a faithful round-trip * This sets `--include-deleted true` #### Include events * If set, all events from the source are included in the backup * If not set, the backup of events is skipped * This sets `--include-events` #### Include Files {% hint style="info" %} This parameter is available in fylr from version **6.34.0**. {% endhint %} * A selector controlling how file bytes are stored in the backup: * *URLs only (do not pack)* — only the file **URLs** are stored; the bytes are fetched from the source during the restore, so the source must stay reachable * *Originals* — pack each file's **original** bytes into the backup directory (`files//…`), making the backup self-contained and byte-for-byte; renditions are regenerated on the target during the restore * *Originals + versions* — also pack the renditions, so that a restore with *Copy file preview versions* uploads them from the backup byte-identical instead of regenerating them * Files kept on the remote (*leave*) are never packed; their real upstream URL is preserved instead * This sets [`--include-files`](/for-system-administrators/migration/backup.md#include-files) #### OAuth2 * Select only if the source instance uses OAuth2 * **easydb5** does not use OAuth2 * this enables the following options: * *OAuth2 Client Id* * Client Id of the source instance * This sets `--client-id fylr-web-frontend` * *OAuth2 Client Secret* * Client Secret of the source instance * Leave empty if the source instance is public * This sets `--client-secret foo` #### Allow Insecure Connection {% hint style="info" %} This parameter is available in fylr from version **v6.14.0**. {% endhint %} * If set, the certificate check for the connection to the source instance is skipped {% hint style="warning" %} Only use this option if you can trust the remote server! {% endhint %} #### Purge or Continue * **Purge** * The existing backup folder is purged and a new backup process is started * This sets `--purge` * **Continue** * A previous backup process is continued * This sets `--continue` ### Fixed parameters The following parameters are set in the background: ``` --size 1000 \ --limit 0 \ --compression 9 \ --log 'example/backup.log' \ --purge ``` ### Progress Click on **Backup** to start the backup process in the background. To see the progress of the backup, select the backup in the overview **List of backups**. This opens a page where you can see the status and the backup log. The generated payloads are listed under the log. When the backup was made with **Include Files**, the packed `files/` directory is shown here too — click into the nested folders to browse the stored file bytes. You can also access this page directly under `/inspect/migration/`, so in this example under `/inspect/migration/example`. ## Restore After a backup was finished, it can be restored to a target **fylr** instance. This uses `fylr restore` to upload the payloads to the **fylr** instance. Not all parameters can be set here. Some parameters are automatically set with a useful default. See also: [Restore Parameters](/for-system-administrators/migration/restore.md#parameters) ### Parameter settings #### Backup * Select one of the backups * This sets `--manifest 'example/manifest.json'` #### URL * URL of the target server **without** API base endpoint * This sets `--server 'http://target.fylr.xyz/api/v1/'` #### Login * Username in the target instance * This sets `--login root` #### Password * Password in the target instance * This sets `--password '12345'` #### File Mode * Method used to upload files, leave empty to not upload files (this is the default) * *Copy files from source (through browser) - `put`* * *Copy files from source (via server) - `rput`* * *Use files from source - `rput_leave`* * The target server stores remote URLs, no data is copied to storage * Use `rput_leave` to not copy files to the restored instance if you want to only test a migration quickly * This sets `--file-api rput` #### File Version * Set a version which will be used as the new original version in the restored instance * *original* (the original asset, no version. This is the default) * *preview* * and other version names (depend on configurations) * If you are not using `rput_leave` use a small version like `preview` to save disk space and process more quickly * This sets `--file-version original` #### Copy file preview versions * Enable this checkbox to not produce local preview versions, but instead copy the source versions (via `put` or `rput`) * If you are using `rput_leave`, the source version is linked as URL * This sets `--upload-versions` {% hint style="info" %} When you restore a backup that was made with **Include Files**, the packed original bytes are uploaded from the local backup directory automatically. Renditions still follow *Copy file preview versions*: enable it to upload them (from the backup if it was made with *Originals + versions*, otherwise from the source), leave it off to have the target regenerate them. For an *Originals*-only backup *Copy file preview versions* cannot be used — the renditions are not packed. {% endhint %} #### Rename Versions {% hint style="info" %} This parameter is available in fylr from version **6.33.0**. {% endhint %} * Rename file versions (renditions) as objects are uploaded into the target instance — useful when the source uses different version names than the target (e.g. `video.1920p` → `1080p`) * The form shows a table with three columns: *File class*, *Source version*, *Target version*; a new empty row is appended automatically as soon as the last one is filled * Leave *Target version* empty to remove the version on the target * When a backup is selected, the table is pre-populated from the restore parameters used on the previous run * On submit, the rows are serialized into `--rename-versions .:,...` See: [renaming renditions during migration](/for-system-administrators/migration/renaming-renditions-during-migration.md) #### Access Token for file URLs This is only needed if the source instance of the backup is a **fylr** and there are files that should be uploaded to the target instance. **fylr** requires all requests to be authenticated. So during the restore process the file URLs need to be accessed in the source fylr, but this will fail if there is no authentication. During the backup, **fylr** adds a signature parameter to the file URLs (`x-fylr-signature`) which can be used to authenticate the request. But this signature is temporary and expires after a fixed time which is configured in the source instance. If you try to restore after a certain time the signatures can be expired and the source instance will not allow access to the files anymore. To override the signature, you can get an OAuth2 Access Token from the source instance which has read rights on these files. If this token is passed, the restore tool will parse the file URLs and remove the signature parameter, and set the `access_token` parameter instead. This sets `--file-api-access-token ` #### Chunk size * Select the batch size for POST requests * Choose between: `10`, `25`, `50`, `100`, `500`, `1000` * This sets `--chunk` #### Include Password * Enable this checkbox to include user password hashes * If this option is `true`, the restore tool checks if there is at least one user where a password hash is present * This sets `--include-password` #### Include events * If set, all events which have an event type that is known by fylr are restored * This means if there are unknown events in the backup (from easydb5), these will not be imported * If not set, no events will be imported * This sets `--include-events` #### Include links to soft-deleted objects {% hint style="info" %} This parameter is available in fylr from version **6.33.0**. {% endhint %} * If set, link wrappers pointing at a soft-deleted target are kept in the restored object instead of being stripped * Only fully meaningful when the source backup was taken with *"Include soft-deleted objects"* — the lookup then resolves to the restored target * Without *"Include soft-deleted objects"* at backup, the lookup defers and the link surfaces as `_purged_or_deferred` on read (the same shape the API serves after a real purge of the target) * This sets `--include-deleted-linked true` #### OAuth2 * Select only if the target instance uses OAuth2 * **easydb5** does not use OAuth2 * this enables the following options: * *OAuth2 Client Id* * Client Id of the target instance * This sets `--client-id web-client` * *OAuth2 Client Secret* * Client Secret of the target instance * Leave empty if the target instance is public * This sets `--client-secret foo` #### Allow Insecure Connection {% hint style="info" %} This parameter is available in fylr from version **v6.14.0**. {% endhint %} * If set, the certificate check for the connection to the target instance is skipped {% hint style="warning" %} Only use this option if you can trust the remote server! {% endhint %} #### Purge or Continue * **Purge** * The target instance is purged and a new restore process is started * This uploads the base config and the data model * This sets `--purge` * **Continue** * A previous restore process of this backup is continued * This sets `--continue` * **No Purge** * Does not purge the target instance * Data model and base config are not uploaded * This mode only uploads base types and user records * Use this after manually purging the target and manually uploading the data model and base config * This sets neither `--purge` nor `--continue`, but `--base-config=-` and `--datamodel=-` See also: [Best Practice > Restoring with and without purge](/for-system-administrators/migration/best-practice.md#restoring-with-and-without-purge) ### Fixed parameters The following parameters are set in the background: ``` --chunk 1000 \ --limit 0 \ --skip-constraints \ --max-parallel-upload-files 4 \ --upload-ignore-files-with-errors \ --timeout-min 15 \ --log 'example/restore.log' \ --purge ``` ### Progress Click on **Restore** to start the restoring process in the background. Confirm the message *This will destroy all data on ""!*. Be sure you want to **delete all data and the complete datamodel** on the target instance. The restore process is always performed with `--purge`. The progress of the restore is the shown in a new page where you can see the log. You also access this page directly under `/inspect/migration/`, so in this example under `/inspect/migration/example`.