Merge pull request #30 from Shayan-Ghani/readme

Updating artifacts.wiki, README and contributing guidelines

Contributing.MD → Contributing.md

@@ -40,7 +40,7 @@ If you encounter any bugs, errors, or have suggestions for improvements:
 
 - **Search existing issues**: Before submitting a new issue, please check if it has already been reported.
 - **Create a new issue**: If it’s a new issue, create one and provide detailed information such as steps to reproduce, expected and actual results, and any relevant screenshots or logs.
-- **Link to related tasks**: If your issue is related to any of the [TODOs](#how-to-use), please reference the corresponding task.
+- **Link to related tasks**: If your issue is related to any of the [TODOs](#https://github.com/Shayan-Ghani/boundary-vault-stack/tree/main/#to-do), please reference the corresponding task.
 
 ### Submitting Pull Requests
 
@@ -51,7 +51,7 @@ When submitting pull requests (PRs):
     git checkout -b feature/your-feature-name
     ```
 
-2. **Make atomic commits**: Ensure each commit is focused and addresses a single change.
+2. **Make atomic commits**: Ensure each commit is focused and addresses a single change by Conforming to the Commit Messages section.
 
 3. **Follow the code style guidelines**: Ensure your code adheres to the project's code style and best practices.
 
@@ -74,10 +74,10 @@ When submitting pull requests (PRs):
 - **Use imperative mood**: Write commit messages as if you are commanding the code to do something (e.g., "Add Vagrantfile for VM provisioning").
 - **Be concise but descriptive**: Provide enough detail to understand the change.
 
-### Testing
+#### Conventions
+  - start your commit with `doc:` in case of any change in wiki.
+  - start your commit with `closes #issue_number :` if your commit closes an issue.
 
-- **Implement Ansible Molecule test cases**: For Ansible roles, write Molecule test scenarios to ensure your roles work as expected.
-- **Automated testing**: Contribute to the CI/CD pipeline by writing GitHub Actions workflows that automate testing.
 
 ## Guidelines for Specific Tasks
 
@@ -100,6 +100,11 @@ When submitting pull requests (PRs):
 
 - **GitHub Actions**: Contribute to the existing CI/CD pipeline by implementing automated testing, linting, and security scans for pull requests.
 
+### Testing
+
+- **Implement Ansible Molecule test cases**: For Ansible roles, write Molecule test scenarios to ensure your roles work as expected.
+- **Automated testing**: Contribute to the CI/CD pipeline by writing GitHub Actions workflows that automate testing.
+
 ## Communication
 
 - **Stay updated**: Regularly check for updates on the project and communicate with the maintainers for any significant contributions.

README.md

@@ -5,20 +5,23 @@ Deploy Self-Hosted HCP Vault and Boundary using End-To-End automation.
 By providing a comprehensive and hands-on experience in Infrastructure as Code (IaC) and Configuration Management along with creating vital deliverables such as documentation and diagrams, this project simulates a real-world infrastructure development that emphasizes End-to-End automation, enabling DevOps Engineers to collaborate and deliver a reliable and production-ready stack to the end-users.
 
 ## How To Use
-**First, make sure you have [READ THE DOCUMENTATION](./artifacts/wiki.md) for instructions on how the stack works.**
+**First, make sure you have [READ THE DOCUMENTATION](./artifacts/wiki.md) for instructions on how the stack and Hashicorp Boundary/Vault work.**
 
-**See a thorough [diagram of the automation workflow](https://linktw.in/PloXtt).**
+**See a thorough [diagram of the automation workflow big picture](https://linktw.in/nWgoiO).**
 
 
 
- To initialize the process run `start.sh` script in your desired environment:
+1. To initialize the process run `start.sh` script in your desired environment:
  ```bash
  #run in dev:
         ./start.sh -e development
  ```
- If you need further assistance on the exit/return code, check out [ wiki ](./artifacts/wiki.md).
 
-**The `ansible-vault-pass` is `BVSTACK`. this is for the sake of simplicity and sample make sure you use a strong password for your ansible vault encrypted files.**
+*If you need further assistance on the exit/return code and configurations, check out [ wiki ](./artifacts/wiki.md).*
+
+2. You'll be prompted to Enter the vault-password to decrypt ansible-vault encrypted files (e.g inventory.ini).
+
+**The `ansible-vault-pass` is `BVSTACK`. This is for the sake of simplicity and sample, make sure you use a strong password for your ansible vault encrypted files.**
 
 ## TO-DO
 > [!NOTE]  
@@ -75,11 +78,6 @@ By providing a comprehensive and hands-on experience in Infrastructure as Code (
 - [ ] Remove vault root token in `cleanup`.
 
 ## Contribution
-all types of contributions is welcomed, read `Contribution.md` for more information.
-
-## Bear In Mind
-- if you have issues with DockerHub make sure you change the image registry in deployments and `prepare_env` role.
-
-- if the target node(s) get restarted, the `vault` gets sealed and `boundary` container will be in restarting mode.
+all types of contribution is welcomed, read [`Contribution.md`](./Contributing.md) for more information.
 
 Copyright © 2024 Shayan Ghani shayan.ghani.tech@gmail.com

artifacts/wiki.md

@@ -1,5 +1,43 @@
 # Boundary-Vault-Stack
 
+## Table of Contents
+- [Getting Started](#getting-started)
+- [About Hashicorp Vault and Boundary](#about-hashicorp-vault-and-boundary)
+- [Workflows](#workflows)
+  - [Vault](#vault)
+  - [Boundary](#boundary)
+- [Configurations](#configurations)
+  - [Environment Variables](#environment-variables)
+- [Return/Exit Codes](#returnexit-codes)
+- [Bear In Mind](#bear-in-mind)
+
+
+## Getting started
+After the server is properly provision and configured you'll have Vault and Boundary up and running. For the sake of education the stack will be initialized with minimum resources for both services including KV and Transit engine (vault) and a series of auth-method, host catalog, credential stores, etc (Boundary). As the Contributions increase, the resources will be enriched accordingly covering more arbitrary resources and features in the format of IaC. 
+
+To grasp what's going on under the hood, you can reach out to the section you wish to explore in this documentation.
+
+
+## About Hashicorp Vault and Boundary
+
+According to Hashicorp documentation, 
+
+[Boundary](https://developer.hashicorp.com/boundary/docs/overview/what-is-boundary) is an identity-aware proxy that simplifies and secures least-privileged access to cloud infrastructure. It enables SSO, just-in-time access, dynamic credentials, and session management.
+
+[Vault](https://developer.hashicorp.com/vault/docs/what-is-vault) is an identity-based secrets and encryption management system. A secret is anything that you want to tightly control access to, such as API encryption keys, passwords, and certificates. Vault provides encryption services that are gated by authentication and authorization methods. Using Vault’s UI, CLI, or HTTP API, access to secrets and other sensitive data can be securely stored and managed, tightly controlled (restricted), and auditable.
+
+### learn more:
+- [Boundary](https://youtu.be/tUMe7EsXYBQ?si=3IFGbMLGTEy_3X1T)
+- [Vault](https://youtu.be/VYfl-DpZ5wM?si=a3Ign_zoUNS92EAP)
+
+## Workflows
+### Vault
+
+
+
+### Boundary
+
+
 
 ## Configurations 
 
@@ -16,6 +54,8 @@
 
 **default**: development
 
+---
+
 #### STACK_INIT (mandatory)
 
 **Description**: When **first** running the stack, `vault-init` and `boundary-init` services are in charge of initiating the basic configurations for `boundary` and `vault`. This variable determines wether this services should be executed or not. So if it's **not** your first time running the stack successfully, set to `false`.
@@ -26,6 +66,16 @@
 
 **default**: true
 
+---
+
+#### SSH_INJECTION (optional)
+
+**Description**:
+
+**Options**:
+  - true
+  - false
+
 ## Return/Exit Codes
 
 In this project, several scripts use return/exit codes to indicate the result of operations. Understanding these codes is essential for diagnosing issues and ensuring proper execution of the scripts. Below is a detailed explanation of each return/exit code used in the project.
@@ -113,4 +163,17 @@ scripts/init.sh vault
 # Exit code: 4
 ```
 
-For further assistance, please open an issue on the [GitHub Issues page](https://github.com/Shayan-Ghani/boundary-vault-stack/issues).
+## Bear In Mind
+- If you have issues with DockerHub make sure you change the image registry in deployments and `prepare_env` role.
+
+- If the target node(s) get restarted, the `vault` gets sealed and `boundary` container will be in restarting mode.
+
+- In case the `vault` container gets restarted, it will be sealed and you'll have an error on your `boudary` container, There manage to get them working together again.
+
+- You can additionally add session recording and other paid plan features.
+
+- Vault is initialized with 1 shared-key to simplify the process, consider increasing the number of keys and threshold for better security.
+
+## Still Having Issues?
+
+For further assistance, feel free to open up a new issue on the [GitHub Issues page](https://github.com/Shayan-Ghani/boundary-vault-stack/issues).