README.md

   1 # Ansible Boilerplate Collection - alexbarton.boilerplate
   2
   3 This Ansible collection provides boilerplate files, plays, roles, scripts etc.
   4 on which new projects that will use Ansible can be based on.
   5
   6 ## Installation
   7
   8 ### Prerequisites
   9
  10 To install this Ansible collection, you need the `ansible-galaxy` command. If
  11 it is not provided by your operating system installation by default, best is
  12 to create a new Python "virtual environment" inside of your project directory
  13 and install Ansible into it, like this:
  14
  15 ```bash
  16 cd ~/src/my-ansible-project
  17 python3 -m venv .venv
  18 ./.venv/bin/pip install -U pip setuptools
  19 ./.venv/bin/pip install ansible
  20 ```
  21
  22 #### Location of the Ansible Boilerplate Collection codebase
  23
  24 By default, the commands here in the README file as well as the scripts of the
  25 Ansible Boilerplate Collection assume that the code of this collection can be
  26 found on the Ansible Galaxy repository with the name "alexbarton.boilerplate".
  27
  28 If you want to override this, you can set the `BOILERPLATE_COLLECTION_SRC`
  29 environment variable to:
  30
  31 * a file name (including path) to a local archive file (e. g.
  32   `/tmp/ansible/alexbarton-boilerplate-0.0.1.tar.gz`)
  33 * a path name to a local Git repository (e. g.
  34   `/usr/local/src/ansible-collection-boilerplate.git`)
  35 * a URL to a remote Git repository (e. g.
  36   `git+https://my.git.server/ansible-collection-boilerplate.git`)
  37 * the name of an Collection stored on the Ansible Galaxy (e. g.
  38   `alexbarton.boilerplate`)
  39
  40 Example:
  41
  42 ```bash
  43 export BOILERPLATE_COLLECTION_SRC=/tmp/ansible/alexbarton-boilerplate-0.0.1.tar.gz
  44 ```
  45
  46 ### Installing the Ansible Boilerplate Collection
  47
  48 The following command will install the Ansible Boilerplate Collection from the
  49 location given in the `BOILERPLATE_COLLECTION_SRC` environment variable (see
  50 above) or from the Ansible Galaxy repository with its default name of
  51 "alexbarton.boilerplate", when the environment variable is not set:
  52
  53 ```bash
  54 ./.venv/bin/ansible-galaxy collection install -p ansible_galaxy \
  55   "${BOILERPLATE_COLLECTION_SRC:-alexbarton.boilerplate}"
  56 ```
  57
  58 ## Initializing a New Project
  59
  60 Once the Ansible Boilerplate Collection is available in the local
  61 `ansible_galaxy/ansible_collections` sub-directory, you can use the
  62 `ansible-boilerplate` command to initialize a new project:
  63
  64 ```bash
  65 ./ansible_galaxy/ansible_collections/alexbarton/boilerplate/bin/ansible-boilerplate init
  66 ```
  67
  68 This initializes an Ansible-based project with some template files, links some
  69 scripts into the local `./bin/` directory (which is created as needed) and
  70 copies the `ansible-boilerplate` command into the `./bin/` directory, too, to
  71 make it available even when the "alexbarton.boilerplate" Ansible Collection is
  72 not yet installed on the local machine (for example, after freshly checking
  73 out the project or running `make distclean`).
  74
  75 It is a good idea to commit this initial state of your new project to your
  76 code repository. For Git, something like this:
  77
  78 ```bash
  79 git init
  80 git add .
  81 git commit -m "Initial commit"
  82 ```
  83
  84 ## Initializing/Upgrading an Existing Project
  85
  86 In an existing and already initialized project the `ansible-boilerplate`
  87 command is available in the `./bin/` directory. You can use it to initialize
  88 the project "from scratch" and to upgrade it like this:
  89
  90 ```bash
  91 ./bin/ansible-boilerplate upgrade
  92 ```
  93
  94 Or, when you use a Python virtual environment and stick to using the Makefile
  95 system provided by this project, you can just use the `make` command itself:
  96
  97 ```bash
  98 make upgrade
  99 ```