Merge pull request #80 from SquirrelCorporation/doc-update-doc

[DOC] Doc update doc

site/.vitepress/config.ts

@@ -92,7 +92,10 @@ export default defineConfig({
               text: 'Adding an unmanaged device (agentless mode)', link: '/docs/add-unamanaged.md'
             },
             {
-              text: 'Playbooks', link: '/docs/playbooks.md'
+              text: 'Playbooks', link: '/docs/playbooks/playbooks.md', items: [
+                { text: 'Local Playbooks Repository', link: '/docs/playbooks/local-playbooks.md'},
+                { text: 'Remote Playbooks Repository', link: '/docs/playbooks/remote-playbooks.md'}
+              ]
             },
             {
               text: 'Services', link: '/docs/services.md'

site/docs/playbooks/local-playbooks.md

@@ -0,0 +1,33 @@
+# Local Playbooks Repositories
+
+:::info Volume path
+By default, according to the docker-compose.yml, local playbooks are stored on your filesystem thanks to a docker volume  `./.data.prod/playbooks:/playbooks`, meaning the file will be located locally on your system in `./.data.prod/playbooks/` 
+:::
+
+## Creating a new local repository
+
+![add-file](/playbooks/add-local.gif)
+
+In Settings > Playbooks tab, in the Local Repository panel, click on the blue button `Add a new local repository`.
+In the modal, enter a name and click `OK`. 
+The playbook repository will be saved on your filesystem.
+
+## Synchronisation 
+
+- SSM **will not** listen to changes (addition/deletion) made outside it's interface unless a manual synchronization is triggered.
+- Any changes made **inside** SSM will be automatically synchronized
+If you believe SSM is desynchronized from the actual files structure of the repository, click on `...` of the `Actions` button of the Repository modal, and click on `Sync to database`
+
+![add-file](/playbooks/manual-sync.gif)
+
+
+## Delete a local repository
+
+:::warning ⚠️ Destructive action
+This action is permanent. Deleting a local repository will effectively delete the underlying files and directories permanently. Proceed with caution! 
+:::
+
+Click on the local repository to open the the modal, click on the `Delete` button.
+
+![add-file](/playbooks/delete-repo.png)
+

site/docs/playbooks/playbooks.md

@@ -0,0 +1,77 @@
+# Playbooks
+
+:::info Ansible playbooks
+"Ansible Playbooks are lists of tasks that automatically execute for your specified inventory or groups of hosts. One or more Ansible tasks can be combined to make a play—an ordered grouping of tasks mapped to specific hosts—and tasks are executed in the order in which they are written."
+[Reference](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_intro.html)
+:::
+
+![playbookspage](/playbooks/playbooks.png)
+
+
+## Creating a directory or an empty playbook
+
+- Directory: On the playbooks directory tree view, *right-click* on the **title** of the parent directory, and on the dropdown menu, click `Create a directory`
+- Empty Playbook: On the playbooks directory tree view, *right-click* on the **title** of the parent directory, and on the dropdown menu, click `Create a playbook`
+
+![add-file](/playbooks/add-file.gif)
+
+:::warning Using your own repositories
+Even if, for the moment, it is possible, we really advice to create your own repository for your custom playbooks instead of using `ssm-core` or `ssm-tools`. Those default repositories will be erased after each update of SSM.
+
+It is better to create a [local](/docs/playbooks/local-playbooks) or [remote](/docs/playbooks/remote-playbooks) repository.
+:::
+## Editing playbooks
+
+You can edit the default playbooks as well as your own custom ones with the editor
+
+Just click on a playbook file and the editor will open.
+
+![edit-file](/playbooks/edit-playbook.gif)
+
+:::warning ⚠️ Playbooks are not saved automatically!
+To prevent any unwanted modifications on playbooks content, playbooks are not saved automatically.
+You must click on the save button (bottom right floating menu)
+::: 
+
+## Syncing playbooks (only for remote repositories)
+
+When you working with a [remote repository](/docs/playbooks/remote-playbooks), a *right-click* on a the root node will offer you additional possibilities, such as Commit & Syncing your changes, or force pulling from the repository
+
+![edit-file](/playbooks/remote-dropdown.gif)
+
+
+## Playbooks Architecture
+
+The Playbooks page displays a list of `Playbooks Repositories`, that can be expanded to view a directory tree.
+
+There are two type of `Playbooks Repository` :
+**Local** and **Remote** repositories, symbolized respectively by the icons:
+- ![localicon](/playbooks/local-storage-folder-solid.svg) 
+- ![localicon](/playbooks/git.svg)
+
+
+## Default playbooks
+
+SSM is shipped with several default playbooks to operate basics tasks such as installing the agent, updating the OS, rebooting, etc...
+Those playbooks are stored in two defaults repositories: `ssm-core` and `ssm-tools`
+```yaml
+- hosts: all
+  tasks:
+  - name: Unconditionally reboot the machine with all defaults
+    ansible.builtin.reboot:
+```
+*Example of playbook for rebooting a device*
+
+`ssm-core` playbooks are starting with '_' chars and cannot be deleted.
+
+
+## Configuration of playbooks: ExtraVar
+
+You can add and share ExtraVars across playbooks.
+When a playbook is opened, click on the configuration tab above it, then click on the (+) icon on the top right side.
+![playbooks2](/playbooks-2.png)
+
+Enter a new name or select the name of an existing Extra var. Your custom var value is saved globally and can be re-used in others playbooks
+![playbooks3](/playbooks-3.png)
+
+To understand more about variables, see the [official Ansible documentation](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html)

site/docs/playbooks/remote-playbooks.md

@@ -0,0 +1,31 @@
+# Remote Playbooks Repositories
+
+Remote playbooks repositories are Git repositories that will be clone to your filesystem as a separate folder.
+
+## Adding a new remote repository
+
+![add-file](/playbooks/add-remote.gif)
+
+To add a git playbooks repository, you must must filled the following information:
+- The `name` of the repo that will be displayed in the Playbooks page
+- The `Git email` associated with the access token
+- The `Git username` associated with the access token
+- The `branch` to checkout and push changes to (e.g `master` or `main`)
+
+![add-file](/playbooks/add-remote-options.png)
+
+## Synchronisation
+
+- SSM **will not** listen to changes (addition/deletion) made outside it's interface unless a manual synchronization is triggered.
+- Any changes made **inside** SSM will be automatically synchronized
+  If you believe SSM is desynchronized from the actual files structure of the repository, click on `...` of the `Actions` button of the Repository modal, and click on `Sync to database`
+
+![add-file](/playbooks/manual-sync.gif)
+
+## Delete a local repository
+
+:::warning ⚠️ Destructive action
+This action is permanent. Deleting a local repository will effectively delete the underlying files and directories permanently. Proceed with caution!
+:::
+
+![add-file](/playbooks/delete-repo.png)

site/docs/quickstart.md

@@ -49,6 +49,8 @@ services:
     env_file: .env
     environment:
       NODE_ENV: production
+    volumes:
+      - ./.data.prod/playbooks:/playbooks
   client:
     image: "ghcr.io/squirrelcorporation/squirrelserversmanager-client:latest"
     restart: unless-stopped

site/docs/services.md

@@ -1,15 +1,15 @@
 # Services
 
 The services page allow you to see and manage the docker containers currently installed on your devices
-![service1](/services/services-1.png)
+![edit-file](/services/services-overview.gif)
 
-Currently, SSM user a king of fork of WhatsUpDocker, using the same flags and filters.
+Currently, SSM uses a kind of fork of WhatsUpDocker, using the same flags and filters.
 
 ## Update available flag
 When an update of the container's image is available, a tag is displayed on the tile
 ![service1](/services/services-3.png)
 
-
 ## Force refresh
 You can force a refresh of the current containers status and available updates by clicking on the top right button
 ![service1](/services/services-2.png)
+

site/docs/settings.md

@@ -10,11 +10,12 @@ The "General Settings" tab enables to you to change the behaviour of SSM globall
 
 ![settings-1](/settings-1.png)
 
-## User Settings
+## Container Registries
 
-The "User Settings" tab only apply to a specific user. Currently, SSM doesn't support multiple users but the feature is planned for a future release.
+The "Container Registries' tab allow to configure several registries so you can watch for container updates on private repositories such as GCR, GHCR, ECR, etc...
+[See more here on how to configure a registry](/docs/registry)
 
-![settings-2](/settings-2.png)
+![settings-1](/settings-2.png)
 
 ## System information
 

site/docs/userguide.md

@@ -3,7 +3,7 @@
 Follow those simple steps to understand the basics of SSM interface
 1. [First time using SSM](/docs/first-time)
 2. [Adding a device](/docs/add-device)
-3. [Playbooks](/docs/playbooks)
+3. [Playbooks](/docs/playbooks/playbooks)
 4. [Executing a playbook](/docs/exec-playbook)
 5. [Settings](/docs/settings)
 6. [Deleting a device](/docs/delete-device)