Restoring on a new server

This scenario is for when the old server is lost or the tracker is moving to a different server. The data is taken from a backup on SFTP storage; the domains and the license are set again. To bring data back on a working installation, use in-place restore.

What to prepare

• An empty server that meets the Server requirements and preparation page, and two domains with DNS records pointing to its IP.
• Access to the storage server with the backup: public IP, SSH port, login, password or private SSH key, and folder. The folder is the same as in the Folder on the server («Папка на сервере») field when connecting the storage, for example /backups.
• The storage server's key fingerprint: you will compare the fingerprint the wizard shows against it.
• The backup encryption key file micator-backup-key-….txt, if the backups are encrypted. Without it, an encrypted backup cannot be restored — see Backup encryption.
• The owner's login and password as of when the backup was created: after the restore you log in with them. If the password is lost, set a new one after the restore with a command on the server — see New owner password.
• A new license key. The key and the binding are not carried over from the backup; your account issues a new key after you unbind the old server — see Transferring a license to another server.

A backup can be restored only on a release with the same data schema and database versions it was created with. The installer puts the current release on the new server. If the old server still works, update the tracker on it and create a fresh backup.

Installation and the first wizard step

Restoring in the wizard is available only on an empty server, before the tracker's first launch.

1. Install the tracker on the new server following the Installation page.
2. Open the wizard link with the access code.
3. Fill in Panel domain («Домен панели»), Tracking domain («Домен трекинга») and Notification email («Email для уведомлений»).
4. Click Check and continue («Проверить и продолжить»).

The wizard issues HTTPS certificates and opens step 2 at a secure address. The step 1 screens are covered on the First-run wizard page.

Do not fill in the owner form on step 2 and do not click Launch tracker («Запустить трекер»). It creates an empty installation, and after that you cannot restore a backup in the wizard.

Connecting the storage

On step 2, above the form, expand the Restore from a backup («Восстановить из резервной копии») block.

1. Fill in Backup server IP, SSH port, SSH login and Storage folder.
2. Click Check server («Проверить сервер»). A line SHA256: … appears under the button — the server fingerprint. The password and key are not sent to the storage server at this step.
3. Compare the fingerprint with your storage server's fingerprint.
4. Check The fingerprint matches my server's key («Отпечаток совпадает с ключом моего сервера») if the fingerprints match.
5. Choose the method in the Authentication field.
6. Enter the password or paste the key.
7. Select the file in the Backup encryption key file field if the backups are encrypted. A line appears under the field: “Key file No. 3F9A-1C2B selected. The wizard does not save it.” («Выбран файл ключа № 3F9A-1C2B. Мастер его не сохраняет.»)
8. Click Show backups («Показать копии»).

Select the key file before clicking Show backups: on an empty server, the key file is the only way for the wizard to tell which backups your tracker created. If you select a different file later, click Show backups again.

The progress of the operation is shown in a line under the Download and verify («Скачать и проверить») button, for example “Reading backups” («Читаем резервные копии»). Error messages appear there too, inside the block.

Backup list

The Completed backup («Завершённая копия») list is divided into groups. Unfinished uploads do not appear in it.

• The newest backup that your file opens is selected first.
• Backups encrypted with another key have no date: it cannot be read without their key. If there are such backups, the wizard warns that they may be newer and names the characters in the name of the required file. To restore a backup that your file opens, check a box like Restore the backup from 3 October, although newer ones may exist («Восстановить копию от 3 октября, хотя могут быть более новые»).
• If the storage server has both encrypted and unencrypted backups, the unencrypted ones are shown after you check No key file — show unencrypted backups («Файла ключа нет — показать копии без шифрования»).
• For an unencrypted backup, the wizard shows a warning: it cannot verify that your tracker created the backup and that it was not swapped on the storage server. To continue, check I understand, restore the unencrypted backup («Понимаю, восстановить копию без шифрования»).

If there are no suitable backups, one of these lines is shown under the list:

• “This file (key No. 3F9A-1C2B) does not open any backup on this server.” («Этот файл (ключ № 3F9A-1C2B) не открывает ни одну копию на этом сервере.») — a file of a different key is selected. The wizard names the number of the key the backups are encrypted with;
• “All backups on this server are encrypted: 12. They cannot be restored without the key file — there is no fallback.” («Все копии на этом сервере зашифрованы: 12. Без файла ключа их не восстановить — запасного способа нет.») — no key file is selected;
• in the list itself, “No backups found — check the storage folder” («Копии не найдены — проверьте каталог хранилища») — the folder has no completed backups.

Selecting and verifying a backup

1. Select a backup in the Completed backup list.
2. Click Download and verify.
3. Wait until the status “Downloading and decrypting the backup. You can close the tab.” («Скачиваем и расшифровываем копию. Вкладку можно закрыть.») changes to a summary. For an unencrypted backup, the status is “Downloading and verifying the backup. You can close the tab.” («Скачиваем и проверяем копию. Вкладку можно закрыть.»)

The wizard downloads the backup to the new server, decrypts it with the key file and checks:

• for an encrypted backup — the signature and that the whole file matches the signed size and checksum;
• the backup contents and the archive checksums;
• that the data schema matches the installed release;
• that the database versions match;
• free space: after the download, at least the size of the unpacked data plus a 20% margin and another 2 GB must remain.

A two-part summary appears under the button:

• “Version: … Size: … Old panel: … New domain to be used: …” («Версия: … Размер: … Прежняя панель: … Будет использован новый домен: …») — the backup version, its size, the old panel domain and the new panel domain from step 1;
• “Backup created 3 October 2026, 04:01 — 8 days ago. Anything that changed in the tracker later will not be restored. Authenticity confirmed by your key file.” («Копия создана 3 октября 2026, 04:01 — 8 дней назад. Всё, что изменилось в трекере позже, восстановлено не будет. Подлинность подтверждена вашим файлом ключа.») For an unencrypted backup, the last sentence is “Unencrypted backup: its authenticity is not confirmed by anything.” («Копия без шифрования: её подлинность ничем не подтверждена.»)

Between them is the New license key («Новый ключ лицензии») field, and below it the Type ВОССТАНОВИТЬ («Введите ВОССТАНОВИТЬ») field.

The wizard keeps only the last downloaded backup on the new server: the previous one, a rejected one and an incompletely downloaded one are deleted right away. The wizard does not save the key file.

If you click Check server or Show backups again after the check, the downloaded backup and the summary are deleted: you will have to download and verify the backup again.

Starting the restore

1. Paste the key into the New license key field. The format is XXXX-XXXX-XXXX-XXXX. You can leave the field empty and enter the key after the restore.
2. In the Type ВОССТАНОВИТЬ field, type ВОССТАНОВИТЬ in capital letters without spaces.
3. Click Restore tracker («Восстановить трекер»).

The “Launching the tracker” («Запускаем трекер») screen opens. The Owner («Владелец») line shows the owner's login from the backup. The status changes in order: “Preparing the tracker” («Подготавливаем трекер»), “Restoring geo databases” («Восстанавливаем геобазы»), “Restoring: …” («Восстанавливаем: …») for each part of the backup, “Checking the database and the send queue” («Проверяем базу и очередь отправок»), “Starting databases and panel” («Запускаем базы и панель»), “Checking readiness” («Проверяем готовность»). Traffic opens only after the readiness check. You can close the tab: the restore continues on the server.

When everything is ready, the “Tracker is ready” («Трекер готов») screen appears with the reminder “Log in with the account from the backup: passwords were not changed.” («Входите учётной записью из резервной копии: пароли не изменялись.») and the line “Backups on the new server are not set up yet: in the panel, open ‘Settings → Backups’, create a new key and connect a storage server.” («Резервные копии на новом сервере ещё не настроены: в панели откройте «Настройки → Резервные копии», создайте новый ключ и подключите сервер хранения.») Click Go to panel («Перейти в панель») — the login page opens. The tracker activates the license key entered in the wizard automatically.

What comes from the backup

Login and check

1. Open https://panel.example.com/login.
2. Log in with the owner's login and password from the backup. No new owner is created, and user passwords do not change.
3. Open Settings → License («Настройки → Лицензия»). The state should be “License active” («Лицензия активна»).
4. Open Settings → Backups («Настройки → Резервные копии»), create a new encryption key and connect the storage server again.
5. Open Logs → Event delivery («Логи → Доставка событий») and find entries with the result Restored from backup · needs reconciliation («Восстановлено из копии · нужна сверка»).

If you see the “Tracker access closed” («Доступ к трекеру закрыт») screen instead of the panel, the license is not active. Enter the new key in the License key («Ключ лицензии») field and click Activate («Активировать»). If the key was entered in the wizard, wait until the old server's confirmation period ends — see Waiting after unbinding.

Entries with the result Restored from backup · needs reconciliation are tasks that were not finished when the backup was created. They will not be sent on their own: the old server may have sent them after the backup was created. Reconcile them with the recipient and only then retry them — see Manual retry.

The encryption key is not part of the backup, so it is created again on the new server. Backups from the old server get the mark “encrypted · another tracker's key” («зашифрована · ключ другого трекера») in the list: do not delete the old key file while you need these backups — only that file opens them.

There are no password files on the new server. The wizard deletes the downloaded backup from the new server when setup is finished — including when the backup was only verified and an empty installation was launched. The backup stays in the storage. If the owner's password from the backup is forgotten, the command sudo micatorctl owner-password sets a new one — see New owner password.

Terminal option: --restore-env

This option is for installing without a browser. The installer takes the .env.production file from the backup and creates a new installation with the old server keys: without them, the backup will not pass verification in the panel. The data is then restored from the panel. The release requirement is the same as in the wizard.

1. Get the server.tar archive of the backup you need. Backups are in the tracker-backups subfolder of the storage folder, each in its own folder. For an unencrypted backup, the archive is in that folder. For an encrypted backup, download the snapshot.age file and decrypt it with the key file — see Opening a backup without the tracker.
2. Extract the .env.production file from the archive.
3. Put the file on the new server outside the installation directory, for example in /root/recovery/, with 0600 permissions. The /opt/micator directory must stay empty until the installation.
4. Run the installer with the command below. In --admin-email, specify the owner login of the old installation.
5. Come up with an owner password for the clean panel and enter it twice. The installer does not take the password from the backup file. For installation without a terminal, pass the password in a file with --owner-password-file — see Unattended installation.
6. Wait for the line “Done. Panel: https://panel.example.com” («Готово. Панель: https://panel.example.com»).
7. Log in to the panel with the login from --admin-email and the password from step 5.
8. Create a new backup encryption key and connect the old backup storage.
9. Run the verification and restore of the backup you need. An encrypted backup from the old server has the mark “encrypted · another tracker's key”: verification needs the old key file and the I understand, verify a backup signed by another server («Понимаю, проверить копию, подписанную другим сервером») checkbox.

sudo bash install.sh --restore-env /root/recovery/.env.production --panel panel.example.com --track track.example.com --email [email protected] --admin-email admin

After the restore, the accounts and passwords from the backup apply; the password from step 5 does not apply to them. Backups, updates and the license key are available only to the account with the login from --admin-email, so it must match the owner login from the backup. When you run the installer again, specify the same file. The installer does not accept an incomplete file: “The recovery file does not contain all required server secrets.” («Файл восстановления не содержит все необходимые серверные секреты.») All parameters are on the install.sh parameters and terminal installation page.

In this option the license is not reset automatically. If the panel shows the “Tracker access closed” screen after installation or after the restore, unbind the server in your account and activate a new key — see Transferring a license to another server.

If something went wrong

The docker command failed (1). («Команда docker завершилась ошибкой (1).»)

This is a general message of the restore block: the wizard could not check the server, read the storage or download the backup. Check that:

• the Backup server IP field has a public IP, not a domain;
• SSH port and SSH login are correct, and the storage server accepts SSH connections from the new server;
• Storage folder is the full path from / without / at the end, and this folder has tracker-backups;
• the password or key is entered and correct. After a page reload, the block's fields are filled in again;
• the storage server's fingerprint has not changed since you clicked Check server.

Verification and launch messages

The backup schema differs. Install the release the backup was created on, then update the tracker. («Схема копии отличается. Установите выпуск, на котором создана копия, затем обновите трекер.»)

The backup was created on a different tracker release.

• The old server still works: update the tracker on it, create a new backup and select it in the wizard. The Show backups button rereads the list.
• The old server is gone: you need an empty server with the release the backup was created on. The release address or file is passed to the installer with the --bundle parameter, see install.sh parameters and terminal installation. After the restore, update the tracker from the panel. An installation made by an earlier release has its project, volumes and services named the old way, starting with tracker — see names of such installations.

You need to retry the launch

The restore stopped with an error; its text is shown on the screen. The selected backup is locked to the installation: you can no longer select a different backup or create an empty installation. Fix the cause and click Retry launch («Повторить запуск»). Launch messages are covered on the Installation errors and how to fix them page.

The message “The backup contains an unsupported geo database file.” («Копия содержит неподдерживаемый файл геобазы.») cannot be fixed by retrying: the cause is in the backup itself — see Tracker geo databases.