Merge pull request #95 from wasmerio/secrets-docs

Add docs for secrets

pages/edge/learn/_meta.json

@@ -3,5 +3,6 @@
   "instaboot": "InstaBoot",
   "deployment-modes": "Deployment Modes",
   "remote-sessions": "Remote Sessions",
-  "connecting-domains-to-edge": "Connecting Custom Domains to Edge"
+  "connecting-domains-to-edge": "Connecting Custom Domains to Edge",
+  "secrets": "Secrets"
 }

pages/edge/learn/secrets.mdx

@@ -0,0 +1,218 @@
+import { Callout } from "nextra-theme-docs";
+import ImageLoader from "@components/ImageLoader";
+import CreateSecrets from "@assets/secrets/secrets_create.png";
+import ListSecrets from "@assets/secrets/secrets_list.png";
+import RevealSecrets from "@assets/secrets/secrets_reveal.png";
+import UpdateDeleteSecrets from "@assets/secrets/secrets_update_delete.png";
+
+### Managing app secrets
+You can manage secure environment variables - from now on simply _secrets_ -
+tied to your apps in two ways: using the Wasmer CLI or directly from the
+dashboard of your app on the [wasmer.io](https://wasmer.io) website.
+
+We designed both these mechanisms to be secure, intuitive and accomodating.
+
+#### Creating secrets
+
+##### From the app dashboard 
+Once reached the dashboard of the app you want to add secrets to, simply click
+on _Settings_ and then select the _Secrets_ tab. From that page, you can see
+the dedicated button used to create a new secret. 
+
+If you have a `.env`-like file defining your secrets and you want to tie them
+to your app in bulk, you can directly upload that file using the dedicated
+button. 
+
+
+<ImageLoader
+  img={CreateSecrets}
+  alt={"The wasmer.io fragment used to create secrets"}
+  className="bg-[#111111] rounded-lg p-4 dark:bg-transparent"
+/>
+
+##### From the CLI
+The `wasmer app secrets create` command allows you to create a new secret for
+your app. The command is able to automatically infer which app you want to tie
+your secrets to from simply executing the command in a directory with an
+`app.yaml` configuration file. The CLI also has the `--app` and `--app-dir`
+flags to specify the app to tie secrets to directly from the command line. 
+
+You can specify the name and value of the secret directly as arguments of the
+CLI command: 
+```sh
+$ wasmer app secrets create MY_NEW_SECRET "its value"
+Succesfully created secret(s):
+MY_NEW_SECRET
+```
+
+If you want to create multiple secrets in bulk, the subcommand offers the 
+`--from-file` flag that allows you to specify a `.env`-like file from which 
+secrets are read off: 
+```sh 
+$ cat .env
+QUOTH_THE_RAVEN="NEVERMORE"
+AGAIN_QUOTH_THE_RAVEN="NEVERMORE"
+
+$ wasmer app secrets create --from-file=.env         
+Succesfully created secret(s):
+QUOTH_THE_RAVEN
+AGAIN_QUOTH_THE_RAVEN
+```
+
+#### Listing secrets
+
+##### From the app dashboard 
+Once reached the dashboard of the app you want to list secrets of, simply
+click on _Settings_ and then select the _Secrets_ tab. In that page, you can
+immediately see the list of secrets tied to your app. 
+
+<ImageLoader
+  img={ListSecrets}
+  alt={"The wasmer.io fragment used to list secrets"}
+  className="bg-[#111111] rounded-lg p-4 dark:bg-transparent"
+/>
+
+It's important to notice that by default the secrets' values are not shown,
+users must instead click on the eye-like button.
+
+##### From the CLI
+The `wasmer app secrets list` command allows you to list - but not reveal - all
+the secrets tied to your app and when they were last updated. The command is
+able to automatically infer which app you want to tie your secrets to from
+simply executing the command in a directory with an `app.yaml` configuration
+file. The CLI also has the `--app` and `--app-dir` flags to specify the app to
+tie secrets to directly from the command line. 
+
+```sh
+$ wasmer app secrets list        
+ Name                   Last updated      
+ MY_NEW_SECRET          11m 59s ago 
+ QUOTH_THE_RAVEN        3m 34s ago  
+ AGAIN_QUOTH_THE_RAVEN  3m 34s ago  
+```
+
+#### Revealing secrets 
+##### From the app dashboard 
+Once reached the dashboard of the app you want to reveal secrets of, simply
+click on _Settings_ and then select the _Secrets_ tab. In that page, you can
+immediately see the list of secrets tied to your app. In order to reveal one of
+them, simply click on the eye-like button!
+
+<ImageLoader
+  img={RevealSecrets}
+  alt={"The wasmer.io fragment used to reveal secrets"}
+  className="bg-[#111111] rounded-lg p-4 dark:bg-transparent"
+/>
+
+It's important to notice that by default the secrets' values are not shown,
+users must instead click on the eye-like button.
+
+##### From the CLI
+The `wasmer app secrets reveal` command allows you to reveal a secret. The
+command is able to automatically infer which app you want to tie your secrets
+to from simply executing the command in a directory with an `app.yaml`
+configuration file. The CLI also has the `--app` and `--app-dir` flags to
+specify the app to tie secrets to directly from the command line. 
+
+```sh
+$ wasmer app secrets reveal QUOTH_THE_RAVEN
+NEVERMORE
+```
+
+If you want to reveal all the secrets tied to the selected app, use the `--all` flag:
+```sh
+$ wasmer app secrets reveal --all                  
+MY_NEW_SECRET="its value"
+QUOTH_THE_RAVEN="NEVERMORE"
+AGAIN_QUOTH_THE_RAVEN="NEVERMORE"
+```
+
+#### Updating secrets 
+##### From the app dashboard 
+Once reached the dashboard of the app you want to update secrets of, simply
+click on _Settings_ and then select the _Secrets_ tab. In that page, you can
+immediately see the list of secrets tied to your app. In order to update one,
+click on the three dots and update the value. 
+
+<ImageLoader
+  img={UpdateDeleteSecrets}
+  alt={"The wasmer.io fragment used to update secrets"}
+  className="bg-[#111111] rounded-lg p-4 dark:bg-transparent"
+/>
+
+##### From the CLI
+The `wasmer app secrets update` command allows you to update an existing secret for
+your app. The command is able to automatically infer which app you want to tie
+your secrets to from simply executing the command in a directory with an
+`app.yaml` configuration file. The CLI also has the `--app` and `--app-dir`
+flags to specify the app to tie secrets to directly from the command line. 
+
+You can specify the name and value of the secret directly as arguments of the
+CLI command: 
+```sh
+$ wasmer app secrets update QUOTH_THE_RAVEN "*nevermore*"
+Succesfully updated secret(s):
+QUOTH_THE_RAVEN
+```
+
+If you want to update multiple secrets in bulk, the subcommand offers the 
+`--from-file` flag that allows you to specify a `.env`-like file from which 
+secrets are read off: 
+```sh 
+$ cat .env
+QUOTH_THE_RAVEN="*nevermore*"
+AGAIN_QUOTH_THE_RAVEN="*neeeevermoreee!*"
+
+$ wasmer app secrets create --from-file=.env         
+Succesfully created secret(s):
+QUOTH_THE_RAVEN
+AGAIN_QUOTH_THE_RAVEN
+```
+
+#### Deleting secrets 
+
+<Callout type='warning'>
+Warning: independently of the method used, once deleted secrets cannot be recovered. 
+</Callout>
+
+##### From the app dashboard 
+Once reached the dashboard of the app you want to delete secrets of, simply
+click on _Settings_ and then select the _Secrets_ tab. In that page, you can
+immediately see the list of secrets tied to your app. In order to update one,
+click on the three dots and delete the secret. 
+
+<ImageLoader
+  img={UpdateDeleteSecrets}
+  alt={"The wasmer.io fragment used to delete secrets"}
+  className="bg-[#111111] rounded-lg p-4 dark:bg-transparent"
+/>
+
+
+##### From the CLI
+The `wasmer app secrets delete` command allows you to delete an existing secret for
+your app. The command is able to automatically infer which app you want to tie
+your secrets to from simply executing the command in a directory with an
+`app.yaml` configuration file. The CLI also has the `--app` and `--app-dir`
+flags to specify the app to tie secrets to directly from the command line. 
+
+
+You can specify the name of the secret directly as arguments of the
+CLI command. In order to avoid users inadvertedly delete a secret, by default 
+the command asks the user for confirmation:
+```sh
+$ wasmer app secrets delete QUOTH_THE_RAVEN 
+✔ Delete secret 'QUOTH_THE_RAVEN'? · yes
+Correctly deleted secret 'QUOTH_THE_RAVEN'
+```
+
+To stop the CLI from asking you safety confirmations, just use the `--force` flag: 
+```sh
+$ wasmer app secrets delete AGAIN_QUOTH_THE_RAVEN --force
+Correctly deleted secret 'AGAIN_QUOTH_THE_RAVEN'
+```
+
+If you don't need any of your secrets anymore and want to delete all 
+the secrets tied to the selected app, you can use the `--all` flag. This command will 
+ask the user confirmation before deleting each secret, one by one. 
+If you are completely sure of deleting all your secrets, you can combine the `--all` flag 
+with the `--force` flag.