Updates and Backups

English · 简体中文 · 日本語

Updates and Backups

Save your work and make a backup before updating, resetting, moving the installation, or experimenting with a large training/library job. Git tracks application code; it does not back up your generated audiobook project.

Return to Home · Related: Installation, Scripts and Review, Troubleshooting

Before an update

1. Let active generation, review, rendering, preparation, training, and export tasks finish, or cancel them from the UI and wait for them to stop.
2. Save the current script in the Script library and retain any needed snapshots/checkpoints. A saved script is useful, but it is not a backup of audio, source uploads, all settings, or every library.
3. Stop the app and any separately launched processes writing to its data.
4. Copy the actual data and settings locations to a separate backup destination. Include companion files and subdirectories, not just the main JSON file.
5. Record the current checkout revision and any local code/environment changes so you can identify the installation that produced the backup.

Stopping writers before copying helps keep JSON state, checkpoint parts, and audio from different moments out of the same backup. Keep the original source book and any irreplaceable recordings independently as well.

What to back up in Pinokio or a normal checkout

With no data-path overrides, the checkout root is the mutable-data root, while settings and uploads retain their older app/ locations.

Work	Default locations to preserve
Application settings	app/config.json
Active book and voice state	annotated_script.json, chunks.json, state.json, voices.json, voice_config.json, character_aliases.json, and related companion/journal files
Generation/review progress	Checkpoint headers and their matching parts directories, snapshots, quality manifests, and review receipts alongside scripts
Source uploads	app/uploads/
Saved scripts	All of scripts/, including voice configuration and metadata companions
Generated and exported audio	voicelines/, cloned_audiobook.mp3, audiobook.m4b, chapter exports, and any separately saved/downloaded export ZIPs
Reusable voices and cast information	voice_library.json, designed_voices/, clone_voices/
Training and dataset work	lora_models/ including its manifest and metadata, lora_datasets/, dataset_builder/, preparer_output/, and any external dataset folders
Advanced settings and evidence	voicelab_config.json, reports/, run_history/, evaluation_reviews/, and logs you want to retain
Separately supplied assets	Local GGUFs, custom model/interpreter settings, downloaded built-in adapters, and any reference files stored outside these folders

The safest complete snapshot is a stopped copy of the checkout plus any configured external data/assets, with environment directories or re-downloadable caches excluded only when you know how to recreate them. Do not restore a Python environment from another operating system or assume a copied GPU environment is portable.

Copy whole checkpoint families. A header can reference a sibling directory named like *.parts-<id>; copying only the JSON can leave it unusable. Likewise, keep a chunk status journal with its matching chunks.json snapshot rather than mixing backups.

Custom paths

• ALEXANDRIA_DATA_DIR moves the app's mutable-data root. With a non-default data root, uploads are under its uploads/ subdirectory and configuration defaults to its config.json.
• ALEXANDRIA_CONFIG_PATH overrides the settings-file path independently, even if the data root is elsewhere.
• Voice Lab, Preparer, custom clone references, and external tools may point to additional folders. Back those up separately.
• Built-in adapter assets remain associated with builtin_lora/ in the checkout rather than being covered solely by a custom data root.

Record these paths and the environment-variable names you use. Protect backup access: configuration can contain API keys, and scripts, recordings, and logs may contain private text or voice data. An env:NAME key reference does not include the secret itself; restore the environment variable securely on the new installation.

Update with Pinokio

1. Complete the backup steps above.
2. Choose Update.
3. Watch the terminal. The launcher stops its known writers, runs git pull, then reruns the core installer.
4. If Git reports local changes or conflicts, preserve those changes and resolve the problem deliberately. Do not discard files merely to make the update finish.
5. When installation completes, start the app and verify Setup, saved scripts, voice libraries, and a short audio sample.
6. If an update changes optional native dependencies, stop the app and rerun Install Voice Tools (Optional) before using those stages.

Update does not guarantee that an interrupted task can resume or that old checkpoints are compatible with changed inputs/settings/code. Keep the backup until your important work opens and the small test passes. Reinstall reruns the core dependency installer; it is not the same action as Reset and does not fetch new code by itself.

Docker upgrades

With the supplied Compose setup:

1. Stop the service with docker compose stop after active tasks have stopped.
2. Back up all of data/, not only data/runtime/. Existing libraries, settings, uploads, and voicelines are mounted from sibling directories.
3. Preserve the existing named Hugging Face cache volume if you want to avoid re-downloading weights. Do not use a volume-removing command as a routine upgrade step.
4. Update the checkout and rebuild/start with docker compose up --build from the same project directory.
5. Check your settings, libraries, and a small job before deleting any backup.

The supplied configuration sets:

• ALEXANDRIA_DATA_DIR=/alexandria/runtime, mounted from data/runtime
• ALEXANDRIA_CONFIG_PATH=/alexandria/config/config.json, backed by data/config
• Separate library/upload/audio mounts under the runtime tree, preserving the existing host directory layout

No host-data move is required for that layout. Older in-container paths such as /alexandria/scripts, /alexandria/voicelines, and /alexandria/app/uploads are symlinks to runtime locations. Keep both config and runtime persistence if replacing Compose with a custom deployment.

Reset warning: active work is removed

Pinokio Reset is destructive. Do not use it as a general troubleshooting shortcut. It stops launcher-managed writers and removes these default checkout paths:

annotated_script.json
voices.json
voice_config.json
character_aliases.json
state.json
app/config.json
chunks.json
cloned_audiobook.mp3
voicelines/

This removes the active script, current voice assignments/state, generated voicelines, merged MP3, and default settings file. The script retains reusable libraries such as saved scripts, designed/clone voices, and training libraries.

The reset list is explicit and uses default checkout paths. It is not a complete data eraser, does not list every report/checkpoint/export, and should not be assumed to clear a custom data/config directory. Conversely, keeping libraries does not preserve the active project listed above. Back up first and inspect reset.js if your installation differs.

Restore and verify

Restore into a stopped installation. Keep each active-book snapshot, its companion files, its voice configuration, and its audio together. Restore libraries with their manifests and metadata, then restore the correct settings path and any required environment variables.

Before continuing a long job:

• Confirm the intended source book and script load.
• Confirm clone references and adapters resolve to real files.
• Listen to existing audio and generate one short test line.
• Review available resume controls; do not assume a checkpoint remains valid after changing its source, model, or settings.
• Keep the backup untouched until these checks succeed.

For audio readiness and final outputs, see Rendering and Export.

Sources

Verified against shipped main at 8c7a33cb310ab9264594a09ca27e48271585094f: update, reset, runtime paths, path overrides, saved-script companions, checkpoint storage, Docker persistence.