Skip to content

docs: add canister snapshots and migration guides, enhance existing docs#374

Merged
marc0olo merged 5 commits intomainfrom
marc0olo/docs-canister-snapshots-migration-guides
Feb 19, 2026
Merged

docs: add canister snapshots and migration guides, enhance existing docs#374
marc0olo merged 5 commits intomainfrom
marc0olo/docs-canister-snapshots-migration-guides

Conversation

@marc0olo
Copy link
Member

Summary

  • Add new Canister Snapshots guide covering create, download, upload, restore, and delete workflows with pre-upgrade backup and state transfer examples
  • Add new Canister Migration guide with two approaches: snapshot-only transfer (new ID) and full migration via migrate-id (preserved ID), including troubleshooting and interruption handling
  • Enhance Tokens and Cycles guide with subaccount documentation (balance checks, transfers, receiver address formats, account identifiers)
  • Enhance Local Development guide with --query flag, proxy canister usage, and network status --json example output
  • Enhance Containerized Networks guide with launcher version pinning section
  • Improve Environments concept doc with api-url / http-gateway-url YAML example
  • Replace outdated "delete and redeploy" advice in Deploying to Specific Subnets with links to the new migration guides
  • Wire up new guides in sidebar navigation, index pages, and cross-links

@marc0olo marc0olo requested a review from a team as a code owner February 18, 2026 18:12
@marc0olo
Copy link
Member Author

Here also a summary of recommendations Claude came up with when creating the docs. I am not sure if a single high-level command makes sense is this involves quite a lot of different operations.

But a few of those recommendations certainly make sense.

CLI Improvement Recommendations: Snapshots and Migration

High Priority

  1. Allow icp canister create without icp.yaml entry — The migration workflow requires a throwaway icp.yaml entry with a dummy build step just to create a target canister. A command like icp canister create --subnet <id> -n ic that returns a canister ID directly would make migration significantly simpler. It would also benefit any workflow where users need to create ad-hoc canisters.

  2. Add icp canister migrate as a single high-level command — The full migration workflow (snapshot create, download, upload, restore, delete snapshot, copy settings, stop both, migrate-id, start, clean up) spans 8+ manual steps across two guides. A single icp canister migrate my-canister --to-subnet <id> that orchestrates all steps would dramatically improve the experience. It could preserve the current step-by-step approach as --dry-run output.

Medium Priority

  1. Auto-remove NNS migration canister as controller — After a successful migrate-id, the NNS migration canister (sbzkb-zqaaa-aaaaa-aaaiq-cai) remains as a controller. The CLI could automatically remove it once migration completes, since there's no reason to keep it. This would eliminate the manual cleanup step.

  2. Copy settings automatically during migrationmigrate-id could read the source canister's settings and apply non-default values to the target before initiating the ID swap. This would eliminate the manual "Copy Settings" step and reduce the risk of forgetting to copy an important setting.

  3. Warn about cycles and offer to drain before migration — The CLI already warns about high cycle balances on the source canister. It could go further by offering to transfer cycles from the source to the user's cycles balance before the destructive migration burns them.

Lower Priority

  1. Add --snapshot flag to migrate-id — Allow migrate-id to handle the snapshot transfer inline: create snapshot on source, upload to target, restore, delete snapshot on target. This would collapse multiple steps into the existing command.

  2. Auto-clean icp.yaml after migration — After a successful migration, the CLI could offer to remove the temporary migration-target entry from icp.yaml and the mappings file, since that canister ID no longer exists.

  3. Add snapshot create --auto-stop — A convenience flag that stops the canister, takes the snapshot, and restarts it, minimizing the commands needed for the common backup workflow.

@marc0olo marc0olo requested a review from viviveevee February 19, 2026 12:50
@marc0olo marc0olo merged commit 4dbc8d2 into main Feb 19, 2026
84 checks passed
@marc0olo marc0olo deleted the marc0olo/docs-canister-snapshots-migration-guides branch February 19, 2026 14:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

Comments