Skip to content

collection of ansible roles and playbooks to enable self-hosters full control of their infrastructure

License

Notifications You must be signed in to change notification settings

selfhostx/ansible

Repository files navigation

Purpose and principles

This collection should enable self-hosters full control of their infrastructure and data (GDPR-focus when external services are used). It will be OSS forever and everyone should be able to integrate it into their infrastructure (or product). We do not re-invent the wheel, if there is a good role or collection somewhere else: we won`t duplicate it (unless important features are missing).

supported distributions:

  • Debian (all supported versions)
  • Ubuntu (supported LTS-Versions)
  • Redhat-based distributions (best-effort-basis), mainly centos stream

2DO in general:

  • CI (travis, gitlab runner, ...?)

Roles

list of own roles (see recommended roles in Roadmap if you miss something).

Basic Roles Description
compute_instance create Linux instances (VMs) via cloud-init with automatic IP-assignment and configuration
baserole configuration role for (new) Linux systems
Roles for apps and services Description
apache apache webserver
ansible semaphore ansible semaphore (ansible GUI)
bacula backup system
certbot certbot (letsencrypt)
dokuwiki dokuwiki (PHP+file-based wiki)
gitea gitea (git server)
libvirt simple virtualization via libvirt+KVM
mailrelay relay mails via postfix
mattermost mattermost (instant messenger)
mysql backup simple mysqldump wrapper
netbox netbox (documentation and IPAM functionality)
nginx (common) nginx common role
postfix mailrelay) postfix mailrelaying
samba (standalone) samba fileserver (standalone, without AD)
uptimekuma uptime kuma (monitoring and status page tool)
vaultwarden vaultwarden is a good zero-knowledge passwordmanager (compatible to bitwarden)
zabbix_checks a couple of useful templates and userparameters for zabbix (monitoring system)

Requirements

minimum ansible version: 2.10

Role requirements

good documentation (preferably a link to a basic user documentation too)

example playbook

proper code formatting (ansible-lint)

classify variables per role

  • required (execution fails if not defined)
  • recommended (common customization)
  • optional (less commonly changed)

dependencies

  • other roles
  • needed pip-modules on target

definition of variables and dependencies (see above) need to be machine-readable to enable automation/custom GUIs) -> 2DO define fileformat!

python3 is required

active maintainers!

Dependencies

the following two files contains all roles and collections which are referenced in example and/or recommended for usage:

ansible setup

pip3 install ansible ansible-lint

python3 (packages or pip):

  • dnspython
  • python3-pip (optional)
  • python3-mysqldb (debian/ubuntu) or python3-mysqlclient (centos&redhat)
  • python3-six
  • python3-apt

if pip is marked as externally managed it might need to use "--break-system-packages" (i.e. on debian12)

License

GPLv3 (unless explicitly stated otherwise)

FAQ

Q: Why not plain shellscripts? A: Shellscript have full flexibility ... but you`ll need to implement everything yourself:

  • templating with condition and variable expansion
  • handlers (run action when certain condition are met, i.e. restart service only when config is changed via template)
  • are not idempotent (it does not have the same result when you run it again)
  • re-implement code stuff that is already available today (ansible galaxy has tons of code)
  • validate config for services that offer it (i.e. prevent broken sudo configs ...)
  • automated/unattended run (installations are not always done interactivly done by a humans!)
  • check-mode (-C) has the ability to show what changes would have been applied
  • error-handling: try to trap errors with pipefail ... that blows up code massively. Example for error-handling in bash (how many of your scripts does implement something similar?):
set -eo pipefail

cleanup() {
# remove temp files
}
trap cleanup 0

error() {
  local parent_lineno="$1"
  local message="$2"
  local code="${3:-1}"
  if [[ -n "$message" ]] ; then
    error_message="Error on or near line ${parent_lineno}: ${message}; exiting with status ${code}"
  else
    error_message="Error on or near line ${parent_lineno}; exiting with status ${code}"
  fi
  echo "$error_message" # for cron
  exit "${code}"
}
trap 'error ${LINENO}' ERR

similiar projects

ansible-collections:

app-stores:

app-installer:

  • bitnami (aquired by vmware)
  • turnkey (own scripts)
  • coolify
  • pikapods (based on docker)
  • CapRover (based on docker, nginx)

deploy tools:

  • vercel
  • ...

organizations supporting hosting: