Separate Pool Creation documentation

README.md

@@ -128,3 +128,51 @@ window.addEventListener('message', responseListener)
 Note: this works for `localhost`out of the box. If you would like to use this feature in production, please submit a PR
 adding your application's public URL to [`src/integrations/allowedOrigins.js`](src/integrations/allowedOrigins.js).
 
+## Creating a custom playground with separate pool creation
+
+As an alternative to a staging environment or the Motoko mainnet playground, the Motoko playground allows for custom, private playgrounds to be deployed. Using a custom playground allows for extensive customization, such as enabling access control by restricting the playground's usage to only allow certain principals, configuring more generous canister timeouts and the amount of available cycles, and allowing some (or all) of the function calls that the mainnet Motoko playground does not allow, such as sending cycles to other canisters. 
+
+Using a custom playground can help simplify development for teams, since the whole team can use a custom playground without needing to manage individual cycle balances. To create a custom playground, **separate pool creation** can be used. 
+
+### Clone the Motoko playground repo with the command:
+
+```
+git clone https://github.com/dfinity/motoko-playground
+```
+
+### To create a separate pool, first use the current Motoko playground pool and `wasm-utils` canisters as the starting point. 
+
+These can be found [here](https://github.com/dfinity/motoko-playground/tree/main/service).
+
+### Then, edit the `pool/Main.mo` file to  change your custom playground settings, such as:
+
+- Add access control as desired, such as creating an `whitelist` of principals that are permitted to use the custom playground.
+
+- Change the Wasm transformation to fit your desired configuration. In some cases, this may just be `wasm = args.wasm_module`, since if there is an `allowlist` in place, the principals allowed to install canisters can be trusted, such as:
+
+```motoko
+let wasm = args.wasm_module;
+```
+
+### Then deploy the pool canister, and if necessary, deploy the `wasm-utils` canister:
+
+```
+dfx deploy pool
+dfx deploy wasm-utils
+```
+
+### Lastly, define the local playground network in your project's `dfx.json` file. In this definition, you will need to set the playground canister's ID (the `pool` canister ID) and define the amount of seconds before a canister is returned to the pool, as shown below:
+
+```json
+"<network name>": {
+  "playground": {
+    "playground_canister": "<canister pool id>",
+    "timeout_seconds": <amount of seconds after which a canister is returned to the pool>
+  },
+  "providers": [
+      "https://icp0.io"
+  ]
+}
+```
+
+If the value `<network name>` is set as `playground`, then the command `dfx deploy --playground` will deploy to your custom playground. Otherwise, the command has to use `--network <network name>`.