Skip to content

Commit

Permalink
refactor(docs): reword documentation, add CONTRIBUTING.md, CODE_OF_CO…
Browse files Browse the repository at this point in the history 
…NDUCT.md
  • Loading branch information
@TerrorSquad
TerrorSquad committed Sep 8, 2024
1 parent 9a70128 commit c902c5b
Show file tree
Hide file tree
Showing 12 changed files with 453 additions and 334 deletions.
44 changes: 44 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
@@ -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.
33 changes: 33 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -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!
102 changes: 18 additions & 84 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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).
6 changes: 3 additions & 3 deletions docs/content/0.index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
::
Expand Down Expand Up @@ -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}
Expand Down
68 changes: 51 additions & 17 deletions docs/content/1.documentation/1.getting-started.mdc
View file
Original file line number Diff line number Diff line change
@@ -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).
::
54 changes: 35 additions & 19 deletions docs/content/1.documentation/2.installation.mdc
View file
Original file line number Diff line number Diff line change
@@ -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:

<!-- TODO: Make this more obviouos -->
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.
Loading

0 comments on commit c902c5b

Please sign in to comment.