From 385d672cd796682bfd5c8a7e294dd9615aacb440 Mon Sep 17 00:00:00 2001 From: Allar Viik Date: Thu, 17 Oct 2024 16:06:18 +0300 Subject: [PATCH] Separated Catapult personalization and customization into separate docs --- docs/{02-how-to-use.md => 20-how-to-use.md} | 7 +++ docs/30-how-to-personalize.md | 35 +++++++++++++++ ...to-customize.md => 40-how-to-customize.md} | 43 ------------------- ...rements.md => 50-template-requirements.md} | 0 version.yml | 2 +- 5 files changed, 43 insertions(+), 44 deletions(-) rename docs/{02-how-to-use.md => 20-how-to-use.md} (97%) create mode 100644 docs/30-how-to-personalize.md rename docs/{03-how-to-customize.md => 40-how-to-customize.md} (60%) rename docs/{04-template-requirements.md => 50-template-requirements.md} (100%) diff --git a/docs/02-how-to-use.md b/docs/20-how-to-use.md similarity index 97% rename from docs/02-how-to-use.md rename to docs/20-how-to-use.md index 99a5bd2c..0d488c94 100644 --- a/docs/02-how-to-use.md +++ b/docs/20-how-to-use.md @@ -5,6 +5,13 @@ Catapult's commands fall into two categories: - External commands - All commands that start with `make` are external commands and are used to manage the Catapult container itself. - Internal commands - All commands that start with `ctp` are internal commands and are used when the user is inside the Catapult container. +Catapult has 2 modes for modifications: + +- Personalization - Where users can set their own preferences that will only affect them. +- Customization - Where preferences are configured in a way that they apply to your team/organization etc. + +Follow the `# How to Personalization` & `# How to Customize` sections if you want to personalize or customize Catapult. + ## Variables When running catapult for the first time it'll ask you to create a new Ansible Vault file and fill it out with your secrets. The secrets are used to connect to the hypervisors, cloud providers, and other services. Besides the required `deployer_username` & `deployer_password` here are some other variables that you might need when using Catapult with [nova.core](https://github.com/ClarifiedSecurity/nova.core) collection: diff --git a/docs/30-how-to-personalize.md b/docs/30-how-to-personalize.md new file mode 100644 index 00000000..a5a35a92 --- /dev/null +++ b/docs/30-how-to-personalize.md @@ -0,0 +1,35 @@ +# How to Personalization + +There several ways to personalize Catapult: + +## Personal Docker Compose file + +`personal/docker-compose-personal.yml` - This file is used to add to, or override the default configuration values defined in `docker/docker-compose.yml`. It can be used to add custom volumes, environment variables, or other settings that are specific to the user. + +Potential use cases for this file include: + +- Mounting custom shell rc files (currently only .zshrc supported) +- Adding extra environmental variables to override default Ansible values that come from `ansible.cfg` +- Mounting custom files into the container + +## Personal aliases file + +`personal/.personal_aliases` - This file is used to add custom shell aliases features etc. + +Potential use cases for this file include: + +- Adding custom aliases that are not available in the defaults +- Adding aliases that are specific to the user +- Adding specific functions that are not available in the defaults + +## Personal makefile configuration + +`personal/.makerc-personal` - This file is used to add custom makefile variables that are specific to the user. Refer to the `.makerc-vars` file for available options. + +Potential use cases for this file include: + +- Adding custom make commands that are specific to the user + +## Personal CLI commands + +`personal/autocomplete.yml` - This file is used to add custom autocomplete commands for `ctp` that are specific to the user. Refer to the default [autocomplete.yml](https://github.com/ClarifiedSecurity/catapult/blob/main/defaults/autocomplete.yml) as an example diff --git a/docs/03-how-to-customize.md b/docs/40-how-to-customize.md similarity index 60% rename from docs/03-how-to-customize.md rename to docs/40-how-to-customize.md index c45842a7..c86fcdc2 100644 --- a/docs/03-how-to-customize.md +++ b/docs/40-how-to-customize.md @@ -1,48 +1,5 @@ # How to customize -Catapult has 2 modes of customization: - -- Personalization - Where users can set their own preferences that will only affect them. -- Customization - Where preferences are configured in a way that they apply to your team/organization etc. - -## Personalization - -There several ways to personalize Catapult: - -### Personal Docker Compose file - -`personal/docker-compose-personal.yml` - This file is used to add to, or override the default configuration values defined in `docker/docker-compose.yml`. It can be used to add custom volumes, environment variables, or other settings that are specific to the user. - -Potential use cases for this file include: - -- Mounting custom shell rc files (currently only .zshrc supported) -- Adding extra environmental variables to override default Ansible values that come from `ansible.cfg` -- Mounting custom files into the container - -### Personal aliases file - -`personal/.personal_aliases` - This file is used to add custom shell aliases features etc. - -Potential use cases for this file include: - -- Adding custom aliases that are not available in the defaults -- Adding aliases that are specific to the user -- Adding specific functions that are not available in the defaults - -### Personal makefile configuration - -`personal/.makerc-personal` - This file is used to add custom makefile variables that are specific to the user. Refer to the `.makerc-vars` file for available options. - -Potential use cases for this file include: - -- Adding custom make commands that are specific to the user - -## Personal CLI commands - -`personal/autocomplete.yml` - This file is used to add custom autocomplete commands for `ctp` that are specific to the user. Refer to the default [autocomplete.yml](https://github.com/ClarifiedSecurity/catapult/blob/main/defaults/autocomplete.yml) as an example - -## Customization - To customize Catapult for your team or organization, a separate git project needs to be created that contains all of the required files. Then users need to be pointed that project using the `MAKEVAR_CATAPULT_CUSTOMIZER_REPO` variable in their `personal/.makerc-personal` file. Use the [Catapult Customizer](https://github.com/ClarifiedSecurity/catapult-customizer) repo as an example. The structure of the customization repo is as follows: diff --git a/docs/04-template-requirements.md b/docs/50-template-requirements.md similarity index 100% rename from docs/04-template-requirements.md rename to docs/50-template-requirements.md diff --git a/version.yml b/version.yml index bbf46337..a9e17c55 100644 --- a/version.yml +++ b/version.yml @@ -1 +1 @@ -version: 5.8.21 +version: 5.8.23