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 99a5bd2..0d488c9 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 0000000..a5a35a9 --- /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 c45842a..c86fcdc 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 bbf4633..a9e17c5 100644 --- a/version.yml +++ b/version.yml @@ -1 +1 @@ -version: 5.8.21 +version: 5.8.23