diff --git a/site/.vitepress/config.ts b/site/.vitepress/config.ts index e88edf66..de8570f9 100644 --- a/site/.vitepress/config.ts +++ b/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' diff --git a/site/docs/playbooks.md b/site/docs/playbooks.md deleted file mode 100644 index ef770b10..00000000 --- a/site/docs/playbooks.md +++ /dev/null @@ -1,44 +0,0 @@ -# Playbook - -:::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) -::: - -## Default playbooks - -SSM is shipped with several default playbooks to operate basics tasks such as installing the agent, updating the OS, rebooting, etc... -```yaml -- hosts: all - tasks: - - name: Unconditionally reboot the machine with all defaults - ansible.builtin.reboot: -``` -*Example of playbook for rebooting a device* - -Default playbooks are starting with '_' chars and cannot be deleted. -You can find the list of default playbooks [here](https://github.com/SquirrelCorporation/SquirrelServersManager/tree/master/server/src/ansible) - -## Editing and creating playbooks - -You can edit the default playbooks as well as creating your own custom ones with the editor - -Go to the **"Playbooks"** section on the left menu, and click on a existing playbook or create a custom one - -![playbooks1](/playbooks-1.png) - -:::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) -::: - -## 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) diff --git a/site/docs/playbooks/local-playbooks.md b/site/docs/playbooks/local-playbooks.md new file mode 100644 index 00000000..5b95576c --- /dev/null +++ b/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) + diff --git a/site/docs/playbooks/playbooks.md b/site/docs/playbooks/playbooks.md new file mode 100644 index 00000000..1182172f --- /dev/null +++ b/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) diff --git a/site/docs/playbooks/remote-playbooks.md b/site/docs/playbooks/remote-playbooks.md new file mode 100644 index 00000000..6433e9e1 --- /dev/null +++ b/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) diff --git a/site/docs/quickstart.md b/site/docs/quickstart.md index 8723c898..02ce1d97 100644 --- a/site/docs/quickstart.md +++ b/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 diff --git a/site/docs/services.md b/site/docs/services.md index 5ec29fe4..e7c90573 100644 --- a/site/docs/services.md +++ b/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) + diff --git a/site/docs/settings.md b/site/docs/settings.md index f2150b4f..61f1e209 100644 --- a/site/docs/settings.md +++ b/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 diff --git a/site/docs/userguide.md b/site/docs/userguide.md index 29716d37..36395a3a 100644 --- a/site/docs/userguide.md +++ b/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) diff --git a/site/public/playbook.png b/site/public/playbook.png index 879feac3..0cdccbc3 100644 Binary files a/site/public/playbook.png and b/site/public/playbook.png differ diff --git a/site/public/playbooks/add-file.gif b/site/public/playbooks/add-file.gif new file mode 100644 index 00000000..3ff2c62d Binary files /dev/null and b/site/public/playbooks/add-file.gif differ diff --git a/site/public/playbooks/add-local.gif b/site/public/playbooks/add-local.gif new file mode 100644 index 00000000..4e581152 Binary files /dev/null and b/site/public/playbooks/add-local.gif differ diff --git a/site/public/playbooks/add-remote-options.png b/site/public/playbooks/add-remote-options.png new file mode 100644 index 00000000..8ee2c326 Binary files /dev/null and b/site/public/playbooks/add-remote-options.png differ diff --git a/site/public/playbooks/add-remote.gif b/site/public/playbooks/add-remote.gif new file mode 100644 index 00000000..ca889672 Binary files /dev/null and b/site/public/playbooks/add-remote.gif differ diff --git a/site/public/playbooks/delete-repo.png b/site/public/playbooks/delete-repo.png new file mode 100644 index 00000000..4cd7570d Binary files /dev/null and b/site/public/playbooks/delete-repo.png differ diff --git a/site/public/playbooks/edit-playbook.gif b/site/public/playbooks/edit-playbook.gif new file mode 100644 index 00000000..f9f91c40 Binary files /dev/null and b/site/public/playbooks/edit-playbook.gif differ diff --git a/site/public/playbooks/git.svg b/site/public/playbooks/git.svg new file mode 100644 index 00000000..2b0e669d --- /dev/null +++ b/site/public/playbooks/git.svg @@ -0,0 +1,3 @@ + + + diff --git a/site/public/playbooks/local-storage-folder-solid.svg b/site/public/playbooks/local-storage-folder-solid.svg new file mode 100644 index 00000000..99d8c722 --- /dev/null +++ b/site/public/playbooks/local-storage-folder-solid.svg @@ -0,0 +1,3 @@ + + + diff --git a/site/public/playbooks/manual-sync.gif b/site/public/playbooks/manual-sync.gif new file mode 100644 index 00000000..aab9af9d Binary files /dev/null and b/site/public/playbooks/manual-sync.gif differ diff --git a/site/public/playbooks/playbooks.png b/site/public/playbooks/playbooks.png new file mode 100644 index 00000000..b140c0f6 Binary files /dev/null and b/site/public/playbooks/playbooks.png differ diff --git a/site/public/playbooks/remote-dropdown.gif b/site/public/playbooks/remote-dropdown.gif new file mode 100644 index 00000000..e00a0a1c Binary files /dev/null and b/site/public/playbooks/remote-dropdown.gif differ diff --git a/site/public/services/services-overview.gif b/site/public/services/services-overview.gif new file mode 100644 index 00000000..e399c457 Binary files /dev/null and b/site/public/services/services-overview.gif differ diff --git a/site/public/settings-2.png b/site/public/settings-2.png index 1dba42ec..7092d6fe 100644 Binary files a/site/public/settings-2.png and b/site/public/settings-2.png differ