Ansible Configuration Management

This repository contains Ansible playbooks and roles for managing and updating Debian servers using a Single Source of Truth (SSoT) pattern with automated CI/CD through Forgejo Actions.

Table of Contents

• Ansible Configuration Management
  • Table of Contents
  • About
  • Repository Structure
  • Quick Start
  • Workflows
  • Local Usage
  • Contributing
  • Support
  • License

About

This repository provides a production-ready Ansible infrastructure with:

• Application Playbooks: Main playbooks for deploying and managing your infrastructure
• Shared Roles: Custom roles for application-specific deployment tasks
• Automated CI/CD: Forgejo Actions workflows for syntax checking and automated deployment
• Vault Security: Encrypted variables for sensitive data
• Flexible Configuration: Easy override mechanisms for custom inventories and variables

Repository Structure

.
├── ansible.cfg              # Ansible configuration
├── group_vars/              # Group-specific variables
├── host_vars/               # Host-specific variables
├── inventories/             # Host inventories
├── roles/                   # Custom Ansible roles
├── templates/               # Jinja2 templates
├── pb.yml                   # Main Ansible playbook
├── pb-ping.yml             # Ping validation playbook
├── requirements.yml         # Ansible Galaxy requirements
├── makefile                 # Build automation
├── LICENSE                  # AGPL License
└── README.md               # This file

Quick Start

Prerequisites

• Ansible 2.10+
• Docker (for pipeline execution)
• SSH access to target hosts
• Vault password for encrypted variables

Local Setup

1. Clone the repository

mkdir ansible_repos
cd ansible_repos
git clone https://git.rollenspiel.monster/ansible-playbooks/code-server.git
cd code-server

2. Install Galaxy requirements

make install

3. Create local vault password file (for local testing only)

echo "your-vault-password" > ../.vault_pass.txt
chmod 600 ../.vault_pass.txt

4. Verify configuration

make validate

5. Dry-run playbook

make check

6. Deploy

make run

Workflows

This repository uses automated workflows managed through Forgejo Actions.

1. Check Workflow (Automatic)

Triggered on push to configured branches:

Check Playbook Syntax
├── Install Dependencies
├── Install Requirements
├── Setup SSH Key
├── Syntax Check (ansible-playbook --syntax-check)
└── Playbook Check (make check with --check --diff)

2. Deploy Workflow (Manual)

Triggered via manual workflow dispatch:

Run Playbook
├── Install Dependencies
├── Install Requirements
├── Setup SSH Key
├── Run Playbook (make update)
└── Cleanup SSH Key

Trigger: Manual trigger from Forgejo Actions UI

Local Usage

Available Commands

make help

Vault Handling

Local with vault file:

echo "your-vault-password" > ../.vault_pass.txt
make check

Local with environment variable:

export VAULT_PASSWORD="your-vault-password"
make check

Pipeline (automatic):

• VAULT_PASSWORD secret is automatically passed via stdin

Makefile Variables

Override any Makefile variable at runtime:

# Override vault password
VAULT_PASSWORD=secret123 make check

# Override playbook arguments
ANSIBLE_ARGS='--extra-vars "key=value"' make run

# Combine both
VAULT_PASSWORD=secret123 ANSIBLE_ARGS='--tags "deploy"' make check

Contributing

Contributions are welcome! Please follow these steps:

1. Create a feature branch

git checkout -b feature/my-improvement

2. Make and test changes locally

make validate
make check

3. Push to your fork

git push origin feature/my-improvement

4. Open a Pull Request with clear description of changes

Testing Guidelines

• Always run make validate before submitting
• Test with make check to validate changes

Support

For issues or questions:

• Check existing Issues in this repository
• Review Ansible documentation: https://docs.ansible.com/
• Check central configuration repository for shared components

License

This Ansible configuration is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

What this means:

• ✅ You can use, modify, and distribute this software freely
• ✅ Internal use within your organization has no restrictions
• ⚠️ If you modify and distribute over a network, you must share your changes under AGPL

This ensures improvements benefit the entire community.

See the LICENSE file for full details.

AGPL FAQ

Q: Can we use this internally without releasing changes?

A: Yes! Only modifications distributed over a network require source code release. Internal use within containers/VMs is unrestricted.

Q: What if we use it in Docker containers or virtual machines?

A: Completely fine. AGPL only applies to modifications accessed or distributed over a network.

Q: Can we add proprietary roles?

A: Yes, as long as they don't network-interact with the AGPL core.

Q: Is this compatible with other licenses?

A: Check FSF License List for compatibility. Generally compatible with: GPLv3, AGPLv3.