Contributing to Ansible Server Setup Playbooks

We welcome contributions to this collection of Ansible playbooks! Whether you're fixing bugs, improving existing playbooks, or adding new ones, your contributions help make server setup easier for everyone.

How to Contribute

1. Fork the Repository

Click the "Fork" button on the GitHub repository page

Clone your fork to your local machine:

git clone https://github.com/jazzybruno/ansible-handy-playbooks.git
cd ansible-handy-playbooks

Add the original repository as an upstream remote:

git remote add upstream https://github.com/jazzybruno/ansible-handy-playbooks.git

2. Setting Up Your Development Environment

Before contributing, ensure you have:

Ansible installed (version 2.9+):

# macOS
brew install ansible

# Ubuntu/Debian
sudo apt update && sudo apt install ansible

# pip (all platforms)
pip install ansible

Test servers for validation:
- Local VM (VirtualBox, VMware, or Vagrant)
- Cloud instance (AWS, DigitalOcean, etc.)
- Docker container for basic testing

3. Creating a New Playbook

When adding a new playbook to the collection:

Step 1: Create Your Branch

git checkout -b feature/add-redis-playbook

Step 2: Create the Playbook

Follow the existing naming convention:

playbooks/07-redis.yml  # Next sequential number

Step 3: Playbook Structure

Your playbook should follow this structure:

---
- name: Install and configure Redis
  hosts: webservers
  become: yes
  vars:
    redis_port: 6379
    redis_bind: "127.0.0.1"
  
  tasks:
    - name: Update package cache
      apt:
        update_cache: yes
      
    - name: Install Redis server
      apt:
        name: redis-server
        state: present
        
    - name: Configure Redis
      template:
        src: ../templates/redis.conf.j2
        dest: /etc/redis/redis.conf
        backup: yes
      notify: restart redis
      
    - name: Start and enable Redis service
      systemd:
        name: redis-server
        state: started
        enabled: yes
        
  handlers:
    - name: restart redis
      systemd:
        name: redis-server
        state: restarted

Step 4: Create Templates (if needed)

If your playbook uses templates, create them in the templates/ directory:

templates/redis.conf.j2

4. Documentation Requirements

Required Documentation

For each new playbook, you must provide:

Playbook header comment explaining what it does
Variable documentation in the playbook or separate vars file
Update the main README.md with:
- Description of what the playbook does
- Usage example
- Required variables
- Any prerequisites

Example Documentation Addition to README.md:

### 07-redis.yml
- Installs Redis server
- Configures Redis with security settings
- Sets up Redis to start on boot
- Configures firewall rules for Redis

Usage:
```bash
ansible-playbook playbooks/07-redis.yml --ask-become-pass


### 5. Testing Your Playbook

#### Required Testing Steps

1. **Syntax Check**:
   ```bash
   ansible-playbook --syntax-check playbooks/07-redis.yml

Dry Run (check mode):

ansible-playbook --check playbooks/07-redis.yml --ask-become-pass

Test on Clean Server:

# Run against a fresh test server
ansible-playbook playbooks/07-redis.yml --ask-become-pass

Idempotency Test:

# Run twice - second run should show no changes
ansible-playbook playbooks/07-redis.yml --ask-become-pass
ansible-playbook playbooks/07-redis.yml --ask-become-pass

Service Verification:

# Verify the service is running
ansible all -m shell -a "systemctl status redis-server" --ask-become-pass

Testing Evidence Required

You must provide evidence that your playbook works. Include in your PR:

Screenshot of successful playbook run showing:
- Command executed
- All tasks completed successfully
- No errors or warnings
Screenshot of service verification showing:
- Service is active and running
- Port is listening (if applicable)
- Basic functionality test
Screenshot of idempotency test showing:
- Second run with "changed=0" for all tasks
- No errors or warnings

Example Testing Session

# Test the Redis playbook
$ ansible-playbook playbooks/07-redis.yml --ask-become-pass

PLAY [Install and configure Redis] ************************************

TASK [Update package cache] *******************************************
ok: [your-server]

TASK [Install Redis server] *******************************************
changed: [your-server]

TASK [Configure Redis] ************************************************
changed: [your-server]

TASK [Start and enable Redis service] ********************************
changed: [your-server]

PLAY RECAP ************************************************************
your-server : ok=4 changed=3 unreachable=0 failed=0

# Verify Redis is running
$ ansible all -m shell -a "redis-cli ping" --ask-become-pass
your-server | CHANGED | rc=0 >>
PONG

# Test idempotency
$ ansible-playbook playbooks/07-redis.yml --ask-become-pass
# Should show changed=0 for all tasks

6. Best Practices

Code Quality

Use descriptive task names that clearly explain what each task does
Add comments for complex logic or non-obvious configurations
Use variables for configurable values (ports, paths, passwords)
Handle different OS versions when necessary
Include error handling for critical tasks

Security Considerations

Never hardcode passwords or sensitive data
Use proper file permissions (600 for private keys, 644 for configs)
Follow the principle of least privilege
Document security implications of your playbook
Test firewall rules don't break existing services

Performance

Use package managers efficiently (update cache once)
Group related tasks when possible
Use handlers for service restarts
Test on resource-constrained systems

7. Submitting Your Contribution

Before Submitting

Playbook passes syntax check
Playbook runs successfully on clean test server
Playbook is idempotent (second run shows no changes)
Service/application works as expected after playbook run
Documentation is updated
Testing screenshots are prepared

Create Pull Request

Commit your changes:

git add .
git commit -m "Add Redis installation and configuration playbook

- Install Redis server from apt repository
- Configure Redis with security settings
- Set up Redis to start on boot
- Add firewall rules for Redis port
- Include template for Redis configuration

Tested on Ubuntu 20.04 and 22.04"

Push to your fork:

git push origin feature/add-redis-playbook

Create Pull Request with:
- Clear title: "Add Redis installation playbook"
- Description including:
  - What the playbook does
  - Operating systems tested
  - Variables required
  - Testing evidence (screenshots)
  - Any breaking changes or prerequisites

Pull Request Template

## Description
Brief description of what this playbook does.

## Testing
- [ ] Syntax check passed
- [ ] Dry run completed successfully
- [ ] Tested on clean Ubuntu 20.04 server
- [ ] Tested on clean Ubuntu 22.04 server
- [ ] Idempotency verified
- [ ] Service functionality verified

## Screenshots
![Successful playbook run](path/to/screenshot1.png)
![Service verification](path/to/screenshot2.png)
![Idempotency test](path/to/screenshot3.png)

## Variables Added
- `redis_port`: Port for Redis to listen on (default: 6379)
- `redis_bind`: IP address to bind Redis to (default: 127.0.0.1)

## Breaking Changes
None / List any breaking changes

## Additional Notes
Any additional context or considerations.

8. Types of Contributions Welcome

New Playbooks

Application installations (Node.js, Python, Java, etc.)
Database systems (MySQL, MongoDB, InfluxDB, etc.)
Monitoring tools (Prometheus, Grafana, ELK stack)
Security tools (fail2ban configurations, security hardening)
Development tools (Git server, CI/CD tools)

Improvements to Existing Playbooks

Bug fixes for failed tasks
Performance optimizations
Security enhancements
Support for additional OS versions
Better error handling

Documentation

Improve existing documentation
Add troubleshooting guides
Create example configurations
Add use case scenarios

9. Getting Help

If you need help with your contribution:

Check existing issues for similar problems
Open an issue describing what you're trying to accomplish
Join discussions on existing pull requests
Test with minimal examples to isolate problems

10. Code Review Process

What Reviewers Check

Functionality: Does the playbook work as described?
Idempotency: Can it be run multiple times safely?
Security: Are there any security concerns?
Documentation: Is it properly documented?
Testing: Is there evidence of proper testing?
Code Quality: Does it follow best practices?

Response Time

Initial review within 3-5 business days
Follow-up reviews within 1-2 business days
Critical security fixes reviewed within 24 hours

Example: Complete Contribution Workflow

Here's a complete example of adding a new MongoDB playbook:

1. Setup

git clone https://github.com/YOUR_USERNAME/ansible-server-setup.git
cd ansible-server-setup
git checkout -b feature/add-mongodb-playbook

2. Create Playbook

Create playbooks/08-mongodb.yml:

---
- name: Install and configure MongoDB
  hosts: webservers
  become: yes
  vars:
    mongodb_port: 27017
    
  tasks:
    - name: Import MongoDB GPG key
      apt_key:
        url: https://www.mongodb.org/static/pgp/server-5.0.asc
        state: present
        
    # ... rest of playbook

3. Test Thoroughly

# Syntax check
ansible-playbook --syntax-check playbooks/08-mongodb.yml

# Test on clean server
ansible-playbook playbooks/08-mongodb.yml --ask-become-pass

# Verify MongoDB is running
ansible all -m shell -a "systemctl status mongod" --ask-become-pass

# Test idempotency
ansible-playbook playbooks/08-mongodb.yml --ask-become-pass

4. Document and Submit

Update README.md with MongoDB section
Take screenshots of testing
Create pull request with all evidence

Thank you for contributing to this project! Your contributions help the entire community manage their infrastructure more effectively.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Contributing to Ansible Server Setup Playbooks

How to Contribute

1. Fork the Repository

2. Setting Up Your Development Environment

3. Creating a New Playbook

Step 1: Create Your Branch

Step 2: Create the Playbook

Step 3: Playbook Structure

Step 4: Create Templates (if needed)

4. Documentation Requirements

Required Documentation

Example Documentation Addition to README.md:

Testing Evidence Required

Example Testing Session

6. Best Practices

Code Quality

Security Considerations

Performance

7. Submitting Your Contribution

Before Submitting

Create Pull Request

Pull Request Template

8. Types of Contributions Welcome

New Playbooks

Improvements to Existing Playbooks

Documentation

9. Getting Help

10. Code Review Process

What Reviewers Check

Response Time

Example: Complete Contribution Workflow

1. Setup

2. Create Playbook

3. Test Thoroughly

4. Document and Submit

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History

CONTRIBUTING.md

File metadata and controls

Contributing to Ansible Server Setup Playbooks

How to Contribute

1. Fork the Repository

2. Setting Up Your Development Environment

3. Creating a New Playbook

Step 1: Create Your Branch

Step 2: Create the Playbook

Step 3: Playbook Structure

Step 4: Create Templates (if needed)

4. Documentation Requirements

Required Documentation

Example Documentation Addition to README.md:

Testing Evidence Required

Example Testing Session

6. Best Practices

Code Quality

Security Considerations

Performance

7. Submitting Your Contribution

Before Submitting

Create Pull Request

Pull Request Template

8. Types of Contributions Welcome

New Playbooks

Improvements to Existing Playbooks

Documentation

9. Getting Help

10. Code Review Process

What Reviewers Check

Response Time

Example: Complete Contribution Workflow

1. Setup

2. Create Playbook

3. Test Thoroughly

4. Document and Submit