Basic usage

Once ce-provision is installed, you can begin using it in a simple way almost immediately. All of the ce-provision roles have their own documentation and ce-provision's scripts expect a normal Ansible playbook. To give you a sense of what you can do, we'll work through an example of installing NGINX and PHP on the controller server (i.e. localhost). Open a terminal again on your controller, then:

1. Switch to the controller user with sudo su -l controller (if you used the --user flag on installation then obviously whatever user you chose)
2. Move to the ce-provision directory with cd ~/ce-provision
3. Make a directory for your playbooks in your config directory with mkdir config/plays
4. With your favourite text editor, open a new playbook file, e.g. vim config/plays/local-webserver.yml
5. Copy the following into the file:

---
- hosts: localhost # run locally
  become: true # use sudo

  tasks:
    - ansible.builtin.import_role: # we use the built in import_role module to load existing roles for specific packages
        name: _init # we always start with the _init role because it sets up a number of things the other roles need
    - ansible.builtin.import_role:
        name: debian/php-common # installs and configures PHP core components
    - ansible.builtin.import_role:
        name: debian/mysql_client # installs and configures the MySQL client
    - ansible.builtin.import_role:
        name: debian/php-cli # installs and configures the PHP CLI
    - ansible.builtin.import_role:
        name: debian/php-fpm # installs and configures PHP-FPM
    - ansible.builtin.import_role:
        name: debian/nginx # installs and configures NGINX
    - ansible.builtin.import_role:
        name: _exit # we always finish with the _exit role because it does some important clean-up tasks

6. Run ce-provision with:

./scripts/provision.sh \
  --repo none \
  --branch none \
  --playbook config/plays/local-webserver.yml \
  --python-interpreter $HOME/ce-python/bin/python3

You should see Ansible execute your playbook and install these components on your controller server. At this point Ansible will use the role defaults, which you can find in the README files for each role or by looking at their individual defaults/main.yml file.

Providing alternative settings

In most cases you will not want all of the default variables. Some of them are just example data, and in some cases you may want different versions, more complexity, and so on. We pre-configure Ansible to merge any variables you provide in your playbook with the defaults of each role to provide a merged set of variables that will be applied. Here's a simple example:

The default version PHP installed by ce-provision at time of writing is PHP 8.1. Let's say you want PHP 7.4 but you're happy with all the rest of the ce-provision defaults. Your playbook can look like this:

---
- hosts: localhost # run locally
  become: true # use sudo

  vars: # we can override any ce-provision defaults we like
    php:
      version:
        - 7.4 # this will install PHP 7.4 instead of PHP 8.1

  tasks:
    - ansible.builtin.import_role:
        name: _init
    - ansible.builtin.import_role:
        name: debian/php-common
    - ansible.builtin.import_role:
        name: debian/mysql_client
    - ansible.builtin.import_role:
        name: debian/php-cli
    - ansible.builtin.import_role:
        name: debian/php-fpm
    - ansible.builtin.import_role:
        name: debian/nginx
    - ansible.builtin.import_role:
        name: _exit

Running your playbook against another server

In order for Ansible to be able to run a playbook against another server, it must be made aware of that server. This is handled via the file at ce-provision/config/hosts/hosts.yml. Let's say you have a server called example1.acme.com and you want to run your playbook against that. These are the steps:

1. Ensure example1.acme.com (the target) is up and running and has a correct DNS entry the controller can use
2. Ensure Python is installed on the target and the controller server has SSH access to the target and is a sudoer (helper scripts coming soon)
3. On the controller, edit ce-provision/config/hosts/hosts.yml and add this:

acme:
  hosts:
    example.acme.com:

4. Edit the first lines of your playbook to look like this:

---
- hosts: example1.acme.com # run via SSH on example1.acme.com
  become: true # use sudo

5. Run ce-provision again but without --python-interpreter because Python has not yet been properly installed on the target:

./scripts/provision.sh \
  --repo none \
  --branch none \
  --playbook config/plays/local-webserver.yml \

This time, assuming your server is available and correctly configured, ce-provision will execute against that machine.