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:

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 login to your controller server as the controller user, like so, where your new server's IP address is 1.2.3.4:

ssh controller.acme.com
sudo su -l controller
cd /home/controller/ce-provision && \
  ./scripts/provision.sh \
  --workspace /home/controller/ce-provision \
  --repo none --branch none \
  --playbook plays/launcher/configure.yml \
  --ansible-extra-vars "_provision_host=1.2.3.4"

Change the value of 1.2.3.4 on the last line to match your IP address or hostname.

This will add the server to hosts.yml in your config repository and install Ansible dependencies and the controller user on the target host. Once this is done 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 new target server (in our example the server with the IP address 1.2.3.4). Open a terminal again on your controller, then:

1. Switch to the controller user, if you haven't already, 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. With your favourite text editor, open a new playbook file, e.g. vim config/plays/1-2-3-4.yml (obviously naming convention is up to you)
4. Copy the following into the file:

---
- hosts: 1.2.3.4 # run on our server at 1.2.3.4 - change to your IP address or hostname
  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

5. Run ce-provision with:

./scripts/provision.sh \
  --workspace /home/controller/ce-provision \
  --repo none \
  --branch none \
  --playbook config/plays/1-2-3-4.yml \
  --python-interpreter $HOME/ce-python/bin/python3

You should see Ansible execute your playbook and install these components on your new target 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 or by reading our documentation website.

Note, ce-provision's bash script assumes the playbook is in the workspace directory. If your playbook is not on the path specified in --workspace then you will need to provide the full path under --playbook and the --absolute-playbook-path flag to tell the script to use it.

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: 1.2.3.4 # run on our server at 1.2.3.4 - change to your IP address or hostname
  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

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