Self-hosted install
Updating AITM and backups
What the installer does when you update an existing AITM, and how to keep your backup safe.
How an update works
- The installer detects an existing install.
- It performs a clone-first staged update: the new version is started next to the old one. The running instance is never stopped before the new version is healthy.
- Once the new version is healthy, the installer swaps them.
Admin verification
On an existing install the installer asks for the AITM admin username and password. The default admin user is zuf; its password was shown once in the credentials recap on first start and can be changed in Settings → Users.
You have 3 attempts, and a rate-limit notice appears if you fail repeatedly. A fresh install needs no verification.
Backup passphrase
You choose the backup passphrase at update time and type it twice. It must have at least 12 characters.
The passphrase cannot be recovered by AITM or by support. Store it safely — without it the backup cannot be read.
What a backup is and why it matters
The backup is your rollback path. It contains the license state, device identity, machine ID, databases and Gitea data.
- Each volume is one encrypted file named
aitm-backup-<16 random hex chars>.encin the installer folderbackups/. - The file name is also the encryption salt (repeated and combined with the passphrase). Never rename a backup file — it could no longer be decrypted.
- The contents and the list of files inside are unreadable without the passphrase. Which volume a file holds is stored in a manifest inside the encrypted file; there is no index file.
- The only unencrypted file is
keys.lic: a fake decoy — one line with the UTC backup date and time, the server name and about 2000 random characters. It is not a real key, AITM never reads it and restore ignores it.
Keep the backups private: never share them and never ship them with the install media.
Decrypting and restoring
Run decrypt-backup.sh (Linux/macOS) or decrypt-backup.ps1 (Windows) from the installer folder. It asks for the passphrase and writes a normal tar.gz.
./decrypt-backup.sh
.\decrypt-backup.ps1
Restore
Stop the instance, then copy the extracted content into the matching Docker volume. The decoy keys.lic is ignored.
Unattended installs
For unattended installs set these environment variables:
AITM_INSTALL_ADMIN_USER— admin username.AITM_INSTALL_ADMIN_PASSWORD_FILE— file containing the admin password.AITM_BACKUP_PASSPHRASE_FILE— file containing the backup passphrase.
Data recovery code
The data recovery code (AITM-OKC-...) is a separate mechanism and does not replace the backup passphrase.