Merge pull request #3485 from dfinity/add-canister-snapshot

add: Docs page on canister snapshots

docs/developer-docs/smart-contracts/maintain/recovery.mdx

@@ -11,13 +11,19 @@ import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
 
 ## Overview
 
-A <GlossaryTooltip>canister</GlossaryTooltip> is managed and maintained by **controllers**. A controller can be a single developer identity, a list of developer identities, or another canister. If a canister does not have a controller, it cannot be upgraded, deleted, or otherwise maintained. Canisters can have several controllers. If access to a canister's controller(s) is lost, the canister cannot be upgraded or further maintained. If a canister's code traps with an unrecoverable error and cannot be upgraded, the canister can potentially be recovered using an NNS proposal.
+A <GlossaryTooltip>canister</GlossaryTooltip> is managed and maintained by **controllers**. A controller can be a single developer identity, a list of developer identities, or another canister. If a canister does not have a controller, it cannot be upgraded, deleted, or otherwise maintained. Canisters can have several controllers. If access to a canister's controller(s) is lost, the canister cannot be upgraded or further maintained. If a canister's code traps with an unrecoverable error and cannot be upgraded, the canister can potentially be recovered using canister snapshots or an NNS proposal.
 
-## Recovering a canister
+## Canister snapshots
 
-If a canister is unable to be upgraded via any of the canister's existing controllers, either due to code failure or loss of access to the canister's controllers, there is no supported method to recover that canister.
+One method for recovering a canister is to roll the canister back to a snapshot if one exists. [Learn more about canister snapshots](snapshots.mdx).
 
-One possible last resort recovery method can be used, however it requires that the canister have the NNS root canister `r7inp-6aaaa-aaaaa-aaabq-cai` configured as a controller of the canister.
+## Recovering a canister that does not have controllers
+
+If a canister is unable to be upgraded via any of the canister's existing controllers, either due to the canister not having controllers or loss of access to the canister's controllers, there is no supported method to recover that canister.
+
+## Recovering a canister with an NNS proposal
+
+If a canister does not have a snapshot that can be used for recovery, one possible last resort recovery method can be used, however it requires that the canister have the NNS root canister `r7inp-6aaaa-aaaaa-aaabq-cai` configured as a controller of the canister.
 
 To add the NNS root canister as a controller of your canister, use the command:
 

docs/developer-docs/smart-contracts/maintain/snapshots.mdx

@@ -0,0 +1,89 @@
+---
+keywords: [beginner, tutorial, maintain canisters, snapshots, canister snapshots]
+---
+
+import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";
+import { GlossaryTooltip } from "/src/components/Tooltip/GlossaryTooltip";
+
+# Snapshots
+
+<MarkdownChipRow labels={["Beginner", "Tutorial"]} />
+
+## Overview
+
+A <GlossaryTooltip>canister</GlossaryTooltip> contains compiled Wasm code and data, such as the canister ID, settings, and Wasm memory. If a canister stops working as expected, traps, or simply needs to be rolled back to a previous version, the developer can use canister snapshots. Developers can take a snapshot of a stopped canister to save the canister's current stable memory, heap memory, data, and Wasm module. This snapshot can be loaded at a later date, rolling the canister back to the code and data saved within that snapshot.
+
+:::info
+Canister snapshots are supported in `dfx` version 0.23.0 and newer.
+:::
+
+## Creating a snapshot
+
+To create a snapshot, first the canister must be stopped. Then, use the `dfx canister snapshot create` command:
+
+```
+dfx canister stop <canister-name>
+dfx canister snapshot create <canister-name>
+```
+
+Only a controller of a canister can take a snapshot or roll a canister back to a snapshot.
+
+:::info
+Currently, only one snapshot per canister can be saved. Taking another snapshot of a canister that already has a snapshot saved will overwrite the previous snapshot.
+:::
+
+:::info
+To take a snapshot of a canister on the mainnet, include the flag `--network ic` in the two commands shown above.
+:::
+
+The canister snapshot ID will be returned:
+
+```
+Created a new snapshot of canister hello_backend. Snapshot ID: 0000000000000000800000000010000a0101
+```
+
+This ID can be used to load the snapshot at a later time. To list all snapshots saved for a canister, use the command:
+
+```
+dfx canister snapshot list <canister-name>
+```
+
+The snapshot ID, snapshot size, and timestamp of when the snapshot was taken will be returned:
+
+```
+0000000000000000800000000010000a0101: 2.39MiB, taken at 2024-09-16 19:40:23 UTC
+```
+
+## Loading a snapshot
+
+To load a saved snapshot, first the canister must be stopped. Then, use the `dfx canister snapshot load` command:
+
+```
+dfx canister stop <canister-name>
+dfx canister snapshot load <canister-name> <snapshot-id>
+```
+
+:::info
+To load a snapshot on the mainnet, include the flag `--network ic` in the two commands shown above.
+:::
+
+Loading a snapshot will replace the canister's current code and data with the snapshot code and data. Any new data that was added to the canister after the snapshot was taken will be deleted.
+
+## Deleting snapshots
+
+To delete a saved snapshot, use the command:
+
+```
+dfx canister snapshot delete <canister-name> <snapshot-id>
+```
+
+:::info
+To delete a snapshot on the mainnet, include the flag `--network ic` in the command shown above.
+:::
+
+## Resources
+
+- [`dfx canister snapshot` reference documentation](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-canister#dfx-canister-snapshot-create).
+
+- [Canister recovery](recovery.mdx).
+

sidebars.js

@@ -176,6 +176,7 @@ const sidebars = {
             "developer-docs/smart-contracts/maintain/logs",
             "developer-docs/smart-contracts/maintain/recovery",
             "developer-docs/smart-contracts/maintain/resource-limits",
+            "developer-docs/smart-contracts/maintain/snapshots",
             "developer-docs/smart-contracts/maintain/state",
             "developer-docs/smart-contracts/maintain/settings",
             "developer-docs/smart-contracts/maintain/storage",