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.

Creating a new target server

We're assuming for the purposes of this quick start guide that you are using a cloud services provider and that when you create a new server you will be asked to provide a public SSH key to access that server via a pre-determined user (for example, with the Debian image at AWS the user is 'admin' and the key to use can be selected from the console). If that is not the case, you will need to manually login following your hosting provider's instructions and add the controller user's public SSH key to a privileged account with SSH access. If you're using such a hosting set-up, you probably know how to do this anyway! Otherwise:

@TODO - steps incomplete

1. Ensure the public SSH key of your controller user on your controller server, created during installation and usually found at /home/controller/.ssh/id_ed25519.pub, is handy and/or uploaded to and available in your cloud services console
2. Create a new server and select/paste your controller's public SSH key (instructions will vary from provider to provider)
3. Now on your controller server as the controller user, copy the playbook at /home/controller/ce-provision/plays/aws_ec2_standalone/ami.yml to somewhere you want to keep your server playbooks on the controller, for example:

ssh controller.acme.com
sudo su -l controller
mkdir -p /home/controller/playbooks/new-server
cp /home/controller/ce-provision/plays/aws_ec2_standalone/ami.yml /home/controller/playbooks/new-server/provision.yml

4. Edit your new playbook, removing the contents of vars and adding new ones for the user we intend to provision, for example:

---
- hosts: default
  become: true

  vars:
    # @TODO - check needed basic variables
    # _init:
    user_provision:
      username: controller
      utility_username: controller
      utility_host: localhost
      groups:
        - bypass2fa
      ssh_keys:
        - "{{ lookup('file', '{{ _ce_provision_data_dir }}/localhost/home/controller/.ssh/id_ed25519.pub') }}"

  tasks:
    - ansible.builtin.import_role:
        name: _init
    - ansible.builtin.import_role:
        name: debian/user_provision
    - ansible.builtin.import_role:
        name: _exit

5. Now on your controller server as the controller user, run a command like this to provision your controller user properly on the new server, where 1.2.3.4 is the IP address if your server - note the comma, it's important:

/home/controller/ce-python/bin/ansible -i 1.2.3.4, /home/controller/playbooks/new-server/provision.yml

This will install the controller user on the target host. Once this is done, you just need to add it to hosts/hosts.yml in your ce-provision-config repository and you can orchestrate its configuration with ce-provision.

Using ce-provision with a playbook from the command line

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 ce-provision file at 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. In your ce-provision-config repository (see previous page) or on the controller (only if you skipped setting up ce-provision-config properly!) edit hosts/hosts.yml and add this:

acme:
  hosts:
    example1.acme.com:

Note, there is lots more information about managing inventories in Ansible here.

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.

Using ce-provision via your config repo and GitLab

While it's useful to know how ce-provision works from the CLI, it's quite a lot nicer to use your config repo to manage your infrastructure. In principle you never need to actually use the server at all, you can do everything from GitLab, via a mix of GitLab CI, Ansible group vars and custom playbooks stored in your ce-provision-config repository.

@TODO