Getting started

Choosing a controller

Firstly, decide where you want your Ansible "control node" to be - this could be anywhere, even your desktop machine or a container! This "control node" will be the machine that will carry out all of your Ansible orchestration against other "managed nodes" or "targets". So think carefully before deciding where your "control node" will be - it will need access to all the servers you expect it to manage, and access to the Internet if it needs to make calls to cloud provider APIs.

Steps for a cloud provider

The most common approach will be to place your controller at a cloud provider somewhere on the Internet. It could really be literally anybody, here's a list of cloud providers on Wikipedia.

1. Login to your cloud provider account and follow their instructions to create a new server with the latest Debian base image
2. Note the IP address of the new server and create two DNS entries with your DNS provider:
   • An A record pointing the hostname (e.g. controller.acme.com) to the IP address
   • (Optional) a CNAME record pointing a subdomain for GitLab (e.g. gitlab.controller.acme.com) to your A record
3. Wait for your DNS records to propagate (become live - you can use a DNS checker)
4. Once your DNS records are live and your server has provisioned, login to the server via SSH or a browser-based terminal to continue

Installing ce-provision

Once you have your Debian (latest) machine up and running and you've logged in, run the following command to download and execute our one-time install script for ce-provision - be sure to make the --gitlab address match your GitLab DNS entry above:

curl -LO https://raw.githubusercontent.com/codeenigma/ce-provision/2.x/install.sh && sudo /bin/sh install.sh --letsencrypt --gitlab gitlab.controller.acme.com

This can also be used to update GitLab and ce-provision. You can find out more about the available options with /bin/sh install.sh -h. If you intend to take advantage of AWS integration, be sure to add the --aws option.

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.

Configuring ce-provision

You can configure ce-provision by providing a Git repository with Ansible settings, customised playbooks, default variables, extra plugins and so forth. By default ce-provision will take its initial config from our example repo which is also a good one to copy to get started. Your options are pretty limitless, so we will focus on two main areas:

• How to build your first remote server using ce-provision
• How to configure ce-provision to manage your AWS account(s)

Configuring the controller to build itself

TODO

Building your first server

TODO

Configuring the controller to orchestrate AWS with Ansible

TODO