diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..9035232 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,44 @@ +# Griffin Code of Conduct + +## Our Pledge + +We, the Griffin community, are committed to creating a welcoming and inclusive environment for everyone, regardless of their background or identity. We value respect, collaboration, and open communication. + +## Our Standards + +We expect all participants in the Griffin community to adhere to the following standards: + +* **Be Respectful:** Treat everyone with kindness and consideration. Avoid any language or behavior that could be considered offensive, discriminatory, or harassing. +* **Be Collaborative:** Work together constructively and be open to feedback. Value diverse perspectives and strive for consensus. +* **Be Welcoming:** Encourage participation from everyone and create an environment where everyone feels comfortable contributing. +* **Be Professional:** Maintain a professional and respectful demeanor in all interactions. + +## Unacceptable Behavior + +Unacceptable behavior includes, but is not limited to: + +* Harassment, discrimination, or intimidation of + any kind. +* Offensive comments or jokes related to gender, sexual orientation, race, ethnicity, religion, disability, or other personal characteristics. +* Personal attacks, insults, or trolling. +* Spamming or other disruptive behavior. + +## Reporting Issues + +If you experience or witness any unacceptable behavior, please report it to the project maintainers. All reports will be handled with discretion and confidentiality. + +## Enforcement + +Project maintainers are responsible for enforcing this Code of Conduct. They will review reported incidents and take appropriate action, which may include: + +* Issuing warnings to individuals. +* Temporarily or permanently banning individuals from the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.0. + + +## Contact + +If you have any questions or concerns about this Code of Conduct, please contact the project maintainers. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b2a4d79 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# Contributing to Griffin + +We welcome contributions from the community to make Griffin even better! Whether you're a seasoned developer or just starting out, your contributions are valuable. + +## How to Contribute + +There are several ways you can contribute to Griffin: + +* **Report Bugs:** If you encounter any bugs or unexpected behavior, please open an issue on the [GitHub repository](https://github.com/TerrorSquad/ansible-post-installation). Provide detailed information about the issue, including steps to reproduce it. +* **Suggest Enhancements:** Have an idea for a new feature or improvement? Feel free to open an issue to discuss it. +* **Improve Documentation:** Help us make the documentation clearer and more comprehensive. You can suggest edits, fix typos, or add new sections. +* **Submit Code:** If you're comfortable with Ansible and want to contribute code, you can fork the repository, make your changes, and submit a pull request. + +## Pull Request Guidelines + +Before submitting a pull request, please ensure: + +* Your code adheres to the project's coding style and conventions. +* You have added appropriate tests for any new functionality. +* Your changes are well-documented. +* You have updated the relevant documentation if necessary. + +## Code of Conduct + +Please note that this project adheres to a [Code of Conduct](code-of-conduct). By participating, you are expected to uphold this code. + +## Getting Help + +If you have any questions or need assistance, feel free to create an issue in the [GitHub repository](https://github.com/TerrorSquad/ansible-post-installation). + +## Thank You! + +We appreciate your interest in contributing to Griffin. Your contributions help make this project a success! diff --git a/README.md b/README.md index 5f295cf..ae660dd 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,30 @@ -# Description +# Griffin: Effortless Linux Configuration -[![Build status](https://github.com/TerrorSquad/ansible-post-installation/actions/workflows/build.yml/badge.svg)](https://github.com/TerrorSquad/ansible-post-installation/actions/workflows/build.yml) +[![Build status](https://github.com/TerrorSquad/ansible-post-installation/actions/workflows/build.yml/badge.svg)](https://github.com/TerrorSquad/ansible-post-installation/actions/workflows/build.yml)   -- Ansible playbook used for installing and configuring software after a system installation -- The playbook should be run as root user (-K flag) and the user name of the non-root user should be passed as an extra argument or defined in defaults/main.yaml. +## Overview -## documentation +Griffin is an Ansible playbook designed to automate the installation and configuration of software on Debian-based Linux systems, making post-installation tasks a breeze. -Documentation is available at [https://terrorsquad.github.io/ansible-post-installation/](https://terrorsquad.github.io/ansible-post-installation/) +## Key Features -## Requirements +* **Automates Post-Installation Tasks:** Configure system settings, install packages, and perform other common tasks. +* **Ensures Consistency:** Maintain uniform configuration across multiple systems. +* **Highly Customizable:** Easily modify playbooks to meet your specific needs. -- OS: Ubuntu 23.04. (tested with Kubuntu 23.04) -- Software: `ansible` +## Supported Systems -1. Install ansible - `sudo apt install -y ansible unzip` -2. Check if the installation was correct by running - `ansible --version` +* Ubuntu +* Linux Mint +* Debian +* WSL (Windows Subsystem for Linux) -It should print out something similar to this this: +## Get Started -```bash -ansible 2.10.8 - config file = None - configured module search path = ['/home/gninkovic/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules'] - ansible python module location = /usr/lib/python3/dist-packages/ansible - executable location = /usr/bin/ansible - python version = 3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0] -``` +For detailed installation instructions, usage guides, and FAQs, please refer to our comprehensive documentation: -### Proxy +[**https://terrorsquad.github.io/ansible-post-installation/**](https://terrorsquad.github.io/ansible-post-installation/) -If you're behind a proxy such as Zscaler, you will need to add the Zscaler root certificate to the system trust store, usually located in `/usr/local/share/ca-certificates/`. After adding the certificate, run `sudo update-ca-certificates` to update the trust store. +## License -There is a helper script in this repo that you can use to add the Zscaler root certificate to the system trust store. Run the following command as root: - -> Note: ❗ Review the script before running it to make sure it's safe. - -```bash -curl -k -s https://raw.githubusercontent.com/TerrorSquad/ansible-post-installation/master/add_zscaler_root_cert.sh | bash -``` - -## How to run - -### Clone this repo, enter the directory and run the following command - -```bash -wget https://github.com/TerrorSquad/ansible-post-installation/archive/refs/heads/master.zip \ -&& unzip master.zip \ -&& cd ansible-post-installation-master -``` - -### Install all software - -```bash -ansible-playbook ./playbook.yml -K -e username=$(whoami) -e=all=true -``` - -#### If you want to change your git user.email and git user.name, pass the git related extra arguments - -```bash -ansible-playbook ./playbook.yml -K -e=all=true -e username=$(whoami) -e "git_user_email='your@email.com'" -e "git_user_name='Your Name'" -``` - -#### If you want to only install CLI tools, run the following command - -```bash -ansible-playbook ./playbook.yml -K -e username=$(whoami) -``` - -#### If you want to also install GUI tools, run the following command - -```bash -ansible-playbook ./playbook.yml -K -e username=$(whoami) -e=gui=true -e=dev_tools_gui=true -``` - -### Flags - -- `-e all=true` - Installs everything. -- `-e dev_tools_gui=true` - Installs developer tools from `dev_tools_gui.yaml`. -- `-e gui=true` - Installs general tools from `general_use_software_gui.yaml`. -- `-e gestures=true` - Installs general tools from `libinput_gestures.yaml`. -- `-e rust=true` - Installs Rust from `rust.yaml`. -- `-e golang=true` - Installs Golang from `golang.yaml`. -- `-e java=true` - Installs SDKMan from `java.yaml`. -- `-e git_user_email="your@email.com` - Sets git user.email config value. -- `-e git_user_name="Your Name` - Sets git user.name config value. -- `username` - defined in `defaults/main.yaml` - can be overridden. Sets the username of the user for who the configuration should happen. -- `-K` - flag used to ask for root password. Required mostly for installing apt packages and updating apt repositories. - -## Copyright - -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. -``` +This project is licensed under the [MIT License](LICENSE.md). diff --git a/docs/content/0.index.md b/docs/content/0.index.md index 3351a31..ee1f8e6 100644 --- a/docs/content/0.index.md +++ b/docs/content/0.index.md @@ -29,7 +29,7 @@ Ansible based post installation script to automate the installation of software - Get a better shell experience with Zsh and antidote. - Install development IDEs like `JetBrains Toolbox`, and `code` (Visual Studio Code). - Install `docker` and `DDEV` for local development. - - Install communication software like `Zoom`, `Slack`, `Teams` + - Install communication software like `Zoom`, `Slack` - Get pre-configured tools like `git`, `zsh`, `nvim`, `terminator` - Customize the installation to your needs with flags and extra arguments. :: @@ -77,9 +77,9 @@ What's included ::card{icon=simple-icons:zoom} #title - Install general use software + Install communication use software #description - Install general use software like `Zoom`, `Slack`, `Teams` + Install communication use software like `Zoom`, `Slack` :: ::card{icon=simple-icons:markdown} diff --git a/docs/content/1.documentation/1.getting-started.mdc b/docs/content/1.documentation/1.getting-started.mdc index a666f0e..54d2855 100644 --- a/docs/content/1.documentation/1.getting-started.mdc +++ b/docs/content/1.documentation/1.getting-started.mdc @@ -1,36 +1,70 @@ -# Introduction +# Griffin: Effortless Linux Configuration -## Overview +## Tired of Tedious Linux Setups? -With **Griffin**, you can transform a newly installed Debian-based Linux system into a fully-configured, efficient, and consistent environment with just one command. This project eliminates the need for manual configuration and repetitive post-installation steps, offering a streamlined approach to setting up a well-configured Linux system. +::p +Setting up a new Linux system or maintaining existing ones can be a time-consuming and frustrating process. Manual installations, complex configurations, and repetitive tasks can quickly drain your productivity. -## Purpose +**Griffin is here to change that.** +:: -Post-installation tasks can be tedious and time-consuming, particularly when managing multiple systems. By automating these tasks with Ansible playbooks, you can ensure consistency and save valuable time. **Griffin** provides a curated set of tasks and configurations that would otherwise require hours of manual setup. This project is designed to assist system administrators and developers in quickly setting up new systems or maintaining existing ones with minimal effort. +## Introducing Griffin -## Why Ansible? +::p +Griffin is your all-in-one solution for automating and streamlining your Linux setup. With Griffin, you can: +:: -Ansible is a powerful automation tool that allows you to define tasks using YAML files. It offers several advantages: +::list +- Transform a fresh install into a powerful workspace in minutes: No more hunting for the right packages or tweaking endless settings. +- Ensure consistency across multiple systems: Say goodbye to configuration drift and hello to predictable, reliable environments. +- Customize your setup with ease: Tailor Griffin to your specific needs and preferences. +:: -- **User-Friendly**: Ansible's syntax is simple and easy to understand. -- **Idempotent Results**: Running a playbook multiple times will yield the same result, ensuring consistent outcomes. -- **Flexible**: Ansible provides a wide range of modules for interacting with different systems. +## Powered by Ansible -## Key Features of **Griffin** +::p +Griffin leverages the power of Ansible, a leading automation tool known for its simplicity and flexibility. Ansible's declarative approach and vast module library make it the perfect engine for automating your Linux configuration. +:: -- **Automate Post-Installation Tasks**: Configure system settings, install packages, and perform other common tasks. -- **Ensure Consistency**: Maintain uniform configuration across multiple systems. -- **Highly Customizable**: Easily modify playbooks to meet your specific needs. +## Key Benefits + +::list +- **Save Time:** Automate tedious post-installation tasks and reclaim your valuable time. +- **Boost Productivity:** Focus on your work, not on configuring your system. +- **Ensure Reliability:** Eliminate manual errors and ensure consistent configurations across all your machines. +- **Simplify Maintenance:** Update and manage your systems effortlessly with Ansible playbooks. +:: + +## Is Griffin Right for You? + +::p +Griffin is ideal for: +:: + +::list +- Developers who want a development-ready environment without the hassle. +- System Administrators who need to manage multiple Linux systems efficiently. +- Linux Enthusiasts who crave a streamlined and personalized setup. +:: ## Supported Systems These playbooks are designed to work on Debian-based Linux systems, including: - +::list - Ubuntu - Linux Mint - Debian - WSL (Windows Subsystem for Linux) +:: + +## Get Started Today! + +::alert{type="info"} +Ready to experience the power of Griffin? Head over to our [Installation Guide](link-to-installation-guide) and unlock a new level of Linux productivity! +:: -## Additional Resources +## Still Have Questions? -For more information on Ansible, refer to the [Ansible Documentation](https://docs.ansible.com/ansible/latest/index.html). +::p +Check out our [FAQ](faq). +:: diff --git a/docs/content/1.documentation/2.installation.mdc b/docs/content/1.documentation/2.installation.mdc index 4dc3326..f804deb 100644 --- a/docs/content/1.documentation/2.installation.mdc +++ b/docs/content/1.documentation/2.installation.mdc @@ -1,37 +1,53 @@ -# Installation +# Installation Guide -## Prerequisites +Let's get Griffin up and running on your system! -Before you begin, ensure you have the following packages installed: +## Before You Start -- ansible (v2.9 or higher) -- unzip +Before diving into the installation, ensure you have the following prerequisites in place: -```sh -sudo apt update -sudo apt install ansible unzip -``` +- **Ansible:** Version 2.9 or higher is required. +- **Unzip:** This utility is needed to extract downloaded files. -Verify the installation by running the following commands: +If you're unsure whether you have these packages installed, you can quickly check using these commands: -```sh +```bash ansible --version +unzip --version ``` -## Proxy +If either of these commands results in an error, you'll need to install the missing package(s). Here's how to do it on Debian-based systems: -If you're behind a proxy such as Zscaler, you will need to add the Zscaler root certificate to the system trust store, usually located in `/usr/local/share/ca-certificates/`. After adding the certificate, run `sudo update-ca-certificates` to update the trust store. +```bash +sudo apt update +sudo apt install ansible unzip +``` -There is a helper script in this repo that you can use to add the Zscaler root certificate to the system trust store. Run the following command as root: +## Behind a Proxy? +If you're behind a proxy like Zscaler, there's an additional step: - +Add the Zscaler root certificate: +You'll need to add the Zscaler root certificate to your system's trust store. This is typically located at `/usr/local/share/ca-certificates/`. +We've included a helper script to simplify this process. -::alert{type="danger"} -Review the script before running it to make sure it's safe. +::alert{type="warning"} +Always review any script before running it to ensure it's safe. :: -```sh -curl -k -s https://raw.githubusercontent.com/TerrorSquad/ansible-post-installation/master/add_zscaler_root_cert.sh | bash +```bash +curl -k -s [https://raw.githubusercontent.com/TerrorSquad/ansible-post-installation/master/add_zscaler_root_cert.sh](https://raw.githubusercontent.com/TerrorSquad/ansible-post-installation/master/add_zscaler_root_cert.sh) | bash ``` + +## Troubleshooting + +If you encounter any issues during the installation, refer to the [FAQ](faq) for assistance. + +## Congratulations! +You've successfully installed **Griffin**! Now you can enjoy a streamlined and efficient Linux experience. + +## Next Steps + +Explore the features and customizations **Griffin** offers. +Learn how to contribute to the project. diff --git a/docs/content/1.documentation/3.usage.mdc b/docs/content/1.documentation/3.usage.mdc index 0a5f33e..fce6452 100644 --- a/docs/content/1.documentation/3.usage.mdc +++ b/docs/content/1.documentation/3.usage.mdc @@ -1,7 +1,6 @@ # Usage - -## How to run +## Getting Started Clone this repo, enter the directory and run the following command @@ -10,13 +9,11 @@ wget https://github.com/TerrorSquad/ansible-post-installation/archive/refs/heads && unzip master.zip \ && cd ansible-post-installation-master ``` +## Running Playbooks +### Default: Install CLI Tools - -## Only install CLI tools - -This is the default playbook that will install CLI tools. -Useful for servers or headless systems such as WSL. +This is the default playbook that installs command-line interface (CLI) tools. It's useful for servers or headless systems like WSL. ```bash ansible-playbook ./playbook.yml -K -e username=$(whoami) @@ -32,7 +29,7 @@ ansible-playbook ./playbook.yml -K -e username=$(whoami) -e "git_user_email='you ## Install GUI tools -This will enable GUI tools installation. +This playbook enables the installation of graphical user interface (GUI) tools. ```bash ansible-playbook ./playbook.yml -K -e username=$(whoami) -e=gui=true -e=dev_tools_gui=true @@ -40,22 +37,26 @@ ansible-playbook ./playbook.yml -K -e username=$(whoami) -e=gui=true -e=dev_tool ## Install all software -To install all software, use the following command: +To install all available software (both CLI and GUI), use the following command: ```bash ansible-playbook ./playbook.yml -K -e username=$(whoami) -e=all=true ``` -## Flags - -- `-e all=true` - Installs everything. -- `-e dev_tools_gui=true` - Installs developer tools from `dev_tools_gui.yaml`. -- `-e gui=true` - Installs general tools from `general_use_software_gui.yaml`. -- `-e gestures=true` - Installs general tools from `libinput_gestures.yaml`. -- `-e rust=true` - Installs Rust from `rust.yaml`. -- `-e golang=true` - Installs Golang from `golang.yaml`. -- `-e java=true` - Installs SDKMan from `java.yaml`. -- `-e git_user_email="your@email.com` - Sets git user.email config value. -- `-e git_user_name="Your Name` - Sets git user.name config value. -- `username` - defined in `defaults/main.yaml` - can be overridden. Sets the username of the user for who the configuration should happen. -- `-K` - flag used to ask for root password. Required mostly for installing apt packages and updating apt repositories. +## Available Flags + +You can customize the installation by using these flags: + + +::list{type="info"} +- `-e all=true`: Installs all software, including both CLI and GUI tools. +- `-e dev_tools_gui=true`: Installs GUI tools specifically for development from the dev_tools_gui.yaml file. +- `-e gui=true`: Installs general-purpose GUI tools from the general_use_software_gui.yaml file +- `-e gestures=true`: Installs tools related to libinput gestures from the libinput_gestures.yaml file +- `-e rust=true`: Installs the Rust programming language and associated tools. +- `-e golang=true`: Installs the Go programming language (Golang) and associated tools +- `-e java=true`: Installs SDKMan, a tool for managing multiple Java versions +- `-e git_user_email="your@email.com" and -e git_user_name="Your Name"`: Sets the Git user configuration values +username: Sets the username for which the configuration should be applied. Can be overridden from its default value in defaults/main.yaml +- `-K`: Prompts for the root password, necessary for certain installation and update tasks +:: diff --git a/docs/content/1.documentation/4.whats-installed.mdc b/docs/content/1.documentation/4.whats-installed.mdc index 8ad310f..3d9a491 100644 --- a/docs/content/1.documentation/4.whats-installed.mdc +++ b/docs/content/1.documentation/4.whats-installed.mdc @@ -1,169 +1,60 @@ - # What's installed -Every linux system should have a set of tools and software that make it easier to use and manage. This project installs a curated set of software that is useful for developers, system administrators, and general users. - -## Shell - -### Zsh - -`zsh` is a powerful shell that provides many features and plugins to enhance your shell experience. This project installs `zsh` as the default shell. - -Learn more about `zsh` [here](https://www.zsh.org/) - -#### Plugin manager - -`antidote` is a plugin manager for `zsh` that provides a rich set of features and plugins to enhance your shell experience. - -Learn more about `antidote` [here](https://getantidote.github.io/) - -#### plugins - -There are many plugins enabled by default, including: - -::list{type="success"} -- zsh-autosuggestions -- zdharma-continuum/fast-syntax-highlighting -- rupa/z -- ohmyzsh/ohmyzsh -- paulirish/git-open -- and many more -:: - - -#### Theme - -The default theme is `powerlevel10k`, which is highly customizable and provides a rich set of features. - -Learn more about `powerlevel10k` [here](https://github.com/romkatv/powerlevel10k) - - -## Development software - -### CLI - -::list{type="success"} -- bat -- bottom -- brew -- broot -- btop -- curl -- curlie -- ddev -- docker (docker-ce) -- docker-compose -- duf -- dust -- eza -- fd -- gh -- git -- git-delta -- git-quick-stats -- go (Golang) -- gping -- htop -- httpstat -- hyperfine -- jq -- lazydocker -- libutempter0 -- lnav -- make -- mdcat -- oha -- procs -- python3-pip -- ripgrep -- rust -- sd -- sdkman (Java / Kotlin / Groovy) -- shellcheck -- tealdeer -- tokei -- tree -- unzip -- vim -- volta (Node.js) -- xh -- yazi -- yq -- zip -:: - - -### GUI - -::list{type="success"} -- alacritty -- code (Visual Studio Code) (if not running on WSL) -- dbeaver-ce -- gitkraken -- graphviz -- guake -- JetBrains Toolbox -- kcachegrind -- postman -- sublime-text -- terminator -- zed (Zed) -:: - - -## General use software - -### CLI - -::list{type="success"} -- eza -- fd -- fzf -- helix -- httpie -- lsd -- ncdu -- neovim -- nvim -- peco -- thefuck -- tlp -- unzip -- vim -- zip -:: - -## GUI - -::list{type="success"} -- bleachbit -- flameshot -- Google Ghrome -- libinput-gestures -- Mailspring -- ModernCSV -- ONLYOFFICE -- openconnect -- papirus-icon-theme -- Redshift -- redshift-gtk -- Rescue Time -- sezanzeb/input-remapper -- Skype -- Slack -- Tixati -- Unified remote -- variety -- Viber -- Vlc -- Zoom -:: - -## Additional window manager - i3 - -## Fonts - -- Hack Mono Nerd Font -- Fira Code Nerd Font -- Fira Mono Nerd Font -- Roboto +This project installs a curated set of tools and software to enhance your Linux experience, catering to developers, system administrators, and general users. + +## Key Features & Benefits + +- **Streamlined Development:** A powerful shell, essential CLI tools, code editors, and version control systems to boost your productivity. +- **Efficient System Management:** Utilities for system monitoring, disk management, process control, and troubleshooting. +- **Enhanced User Experience:** Improved terminal experience, desktop customization, and convenient applications for everyday tasks. + +## Tool Categories + +### Shell & Terminal + +- **Zsh:** A powerful shell with enhanced features and plugins. +- **Powerlevel10k:** A customizable and visually appealing Zsh theme. +- **Antidote:** A plugin manager for Zsh, providing a rich ecosystem of extensions. +- **Alacritty:** A fast and customizable GPU-accelerated terminal emulator. +- **Terminator:** A feature-rich terminal emulator with split-screen capabilities. +- **Guake:** A drop-down terminal for quick access. + +### Development Essentials + +- **Code Editors & IDEs:** Visual Studio Code, Sublime Text, Vim, Neovim, Helix, Zed +- **Databases & DBMS:** DBeaver Community Edition +- **Version Control:** Git, GitKraken, git-delta, git-quick-stats, gh (GitHub CLI) +- **Package Managers:** Brew, SDKMAN (Java, Kotlin, Groovy) +- **DevOps & Sysadmin:** Docker, Docker Compose, Lazydocker, ddev (Open source tool for developers to simplify Docker usage) +- **Programming Languages:** Go, Python, Rust, Node.js (via Volta) +- **CLI Tools:** bat, bottom, broot, curl, curlie, make, mdcat, oha, shellcheck, tealdeer, tokei, tree, yazi, yq + +### System & Productivity + +- **File Management:** eza, fd, fzf, lsd, ncdu, unzip, zip +- **System Monitoring & Control:** btop, htop, procs, tlp +- **Productivity Boosters:** helix, libinput-gestures, peco, thefuck, variety +- **System Utilities:** bleachbit, RescueTime, sezanzeb/input-remapper, Unified Remote + +### Internet & Networking + +- **Web Browser:** Google Chrome +- **Networking Tools:** curl, curlie, gping, httpie, httpstat, openconnect, xh +- **Torrent Client:** Tixati + +### Communication & Office + +- **Communication:** Skype, Slack, Viber, Zoom +- **Office Suite:** ONLYOFFICE +- **Email Client:** Mailspring + +### Multimedia & Graphics + +- **Media Player:** VLC +- **Screenshot Tool:** Flameshot +- **Graph Visualization:** Graphviz + +### Additional Enhancements + +- **Window manager:** i3 +- **Fonts:** Hack Mono Nerd Font, Fira Code Nerd Font, Fira Mono Nerd Font, Roboto diff --git a/docs/content/1.documentation/5.testing.mdc b/docs/content/1.documentation/5.testing.mdc index 196e82f..96a9271 100644 --- a/docs/content/1.documentation/5.testing.mdc +++ b/docs/content/1.documentation/5.testing.mdc @@ -1,27 +1,54 @@ +# Testing with Vagrant -# Testing - Vagrant +To test the Ansible playbook locally, you can leverage the power of Vagrant to create a virtualized environment. -To the the playbook locally we can use Vagrant. +## Prerequisites -There are `Vagrantfile` and a `playbook_vagrant.yml` files. These two are set up for working with Vagrant and testing the configuration. +Before you begin, make sure you have the following software installed on your system: -- Install Vagrant +* **Vagrant:** A tool for building and managing virtual machine environments. +* **VirtualBox:** A virtualization platform that Vagrant can use to create the virtual machine. - ```bash - sudo apt install -y vagrant virtualbox - ``` +You can install these on Debian-based systems using the following command: -- Create a Vagrant box and provision it +```bash +sudo apt install -y vagrant virtualbox +``` - ```bash - vagrant up --provision - ``` +## Testing Steps -- Force destroy and recreate the box +Follow these steps to set up and test your Ansible playbook with Vagrant: - ```bash - vagrant destroy --force && vagrant up --provision - ``` +1. Navigate to the Project Directory: + ::alert + Ensure you are in the root directory of your Griffin project where the Vagrantfile and playbook_vagrant.yml files are located. + :: -> Vagrantfile will use `playbook_vagrant.yml` file as the `Ansible` entrypoint. -> Box name `ubuntu/mantic64` - +2. Create and Provision the Vagrant Box: + Run the following command to create a new Vagrant box and provision it with your Ansible playbook: + ```bash + vagrant up --provision + ``` + +This will: + +1. Download the specified Ubuntu image (if not already present). +2. Create a virtual machine based on that image. +3. Execute the `playbook_vagrant.yml` Ansible playbook to configure the virtual machine. +4. Force Destroy and Recreate (Optional): + +If you need to start from a clean slate or make changes to your Ansible playbook, you can force destroy the existing box and recreate it with the latest configuration: + +```bash +vagrant destroy --force && vagrant up --provision +``` + +## Important Notes + +::alert{type="info"} +Vagrantfile Configuration: The Vagrantfile in your project is already configured to use playbook_vagrant.yml as the Ansible entry point. +Base Box: The Vagrant setup uses the ubuntu/mantic64 box. You can find more information about this box on the Vagrant Cloud. +:: + +## Troubleshooting +If you encounter any issues during the testing process, consult the [FAQ](faq) for assistance. diff --git a/docs/content/1.documentation/6.faq.mdc b/docs/content/1.documentation/6.faq.mdc index 4c5188d..95eef7e 100644 --- a/docs/content/1.documentation/6.faq.mdc +++ b/docs/content/1.documentation/6.faq.mdc @@ -1,11 +1,73 @@ -# FAQ +# Frequently Asked Questions (FAQ) -## What package manager is used? +## General -- This playbook uses `apt` package manager for installing packages on Debian-based systems. -- It also uses `brew` for installing other packages not available in the default repositories. +### What package manager is used? -## Installation fails on a `homebrew` task +::list +- This playbook primarily uses `apt` for installing packages on Debian-based systems. +- It also utilizes `brew` (Homebrew) for installing additional packages not available in the default repositories. +:: +### Installation fails on a `homebrew` task + +::list - If the installation fails on a `homebrew` task, it is most likely due to a network issue. - Check your internet connection and try running the playbook again. +:: + +## Troubleshooting + +### I'm getting an error about missing permissions. + +::alert{type="warning"} +Ensure you are running the Ansible playbook with `sudo` or as the `root` user. Some tasks require elevated privileges to modify system settings or install packages. +:: + +### The installation is taking a very long time. + +::p +The installation time can vary depending on your internet connection speed and the number of packages being installed. If it seems excessively long, check your network connectivity and ensure no other processes are heavily utilizing your system resources. +:: + +### Can I customize the list of installed software? + +::p +Absolutely! Griffin is designed to be flexible. You can edit the Ansible playbooks (`.yml` files) to add, remove, or modify the list of installed software to suit your specific needs. +:: + +### How do I update the installed software? + +::p +You can rerun the Ansible playbook to update the installed software to their latest versions. The idempotent nature of Ansible ensures that only necessary updates will be performed. +:: + +### I'm encountering an error I can't resolve. Where can I get help? + +::p +If you're facing an issue you can't troubleshoot, you can: +:: +::list +- Create an issue on the project's GitHub repository. +:: + +## Contributing + +### How can I contribute to Griffin? + +::p +We welcome contributions from the community! You can contribute by: +:: +::list +- Reporting bugs or suggesting enhancements. +- Submitting pull requests with code improvements or new features +- Helping with documentation or translations +:: + +::p +Please refer to the [Contributing Guidelines](CONTRIBUTING) for detailed information on how to get involved +:: + +## Other Questions + +If you have any other questions not addressed here, feel free to reach out to the community or open an issue on the project's GitHub repository. diff --git a/docs/content/1.documentation/7.CONTRIBUTING.mdc b/docs/content/1.documentation/7.CONTRIBUTING.mdc new file mode 100644 index 0000000..b2a4d79 --- /dev/null +++ b/docs/content/1.documentation/7.CONTRIBUTING.mdc @@ -0,0 +1,33 @@ +# Contributing to Griffin + +We welcome contributions from the community to make Griffin even better! Whether you're a seasoned developer or just starting out, your contributions are valuable. + +## How to Contribute + +There are several ways you can contribute to Griffin: + +* **Report Bugs:** If you encounter any bugs or unexpected behavior, please open an issue on the [GitHub repository](https://github.com/TerrorSquad/ansible-post-installation). Provide detailed information about the issue, including steps to reproduce it. +* **Suggest Enhancements:** Have an idea for a new feature or improvement? Feel free to open an issue to discuss it. +* **Improve Documentation:** Help us make the documentation clearer and more comprehensive. You can suggest edits, fix typos, or add new sections. +* **Submit Code:** If you're comfortable with Ansible and want to contribute code, you can fork the repository, make your changes, and submit a pull request. + +## Pull Request Guidelines + +Before submitting a pull request, please ensure: + +* Your code adheres to the project's coding style and conventions. +* You have added appropriate tests for any new functionality. +* Your changes are well-documented. +* You have updated the relevant documentation if necessary. + +## Code of Conduct + +Please note that this project adheres to a [Code of Conduct](code-of-conduct). By participating, you are expected to uphold this code. + +## Getting Help + +If you have any questions or need assistance, feel free to create an issue in the [GitHub repository](https://github.com/TerrorSquad/ansible-post-installation). + +## Thank You! + +We appreciate your interest in contributing to Griffin. Your contributions help make this project a success! diff --git a/docs/content/1.documentation/8.CODE-OF-CONDUCT.md b/docs/content/1.documentation/8.CODE-OF-CONDUCT.md new file mode 100644 index 0000000..9035232 --- /dev/null +++ b/docs/content/1.documentation/8.CODE-OF-CONDUCT.md @@ -0,0 +1,44 @@ +# Griffin Code of Conduct + +## Our Pledge + +We, the Griffin community, are committed to creating a welcoming and inclusive environment for everyone, regardless of their background or identity. We value respect, collaboration, and open communication. + +## Our Standards + +We expect all participants in the Griffin community to adhere to the following standards: + +* **Be Respectful:** Treat everyone with kindness and consideration. Avoid any language or behavior that could be considered offensive, discriminatory, or harassing. +* **Be Collaborative:** Work together constructively and be open to feedback. Value diverse perspectives and strive for consensus. +* **Be Welcoming:** Encourage participation from everyone and create an environment where everyone feels comfortable contributing. +* **Be Professional:** Maintain a professional and respectful demeanor in all interactions. + +## Unacceptable Behavior + +Unacceptable behavior includes, but is not limited to: + +* Harassment, discrimination, or intimidation of + any kind. +* Offensive comments or jokes related to gender, sexual orientation, race, ethnicity, religion, disability, or other personal characteristics. +* Personal attacks, insults, or trolling. +* Spamming or other disruptive behavior. + +## Reporting Issues + +If you experience or witness any unacceptable behavior, please report it to the project maintainers. All reports will be handled with discretion and confidentiality. + +## Enforcement + +Project maintainers are responsible for enforcing this Code of Conduct. They will review reported incidents and take appropriate action, which may include: + +* Issuing warnings to individuals. +* Temporarily or permanently banning individuals from the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.0. + + +## Contact + +If you have any questions or concerns about this Code of Conduct, please contact the project maintainers.