-
Notifications
You must be signed in to change notification settings - Fork 5
Getting started
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.
As previously noted, Debian Linux is not essential for the controller server, however it is recommended as any other operating system will be untested for the foreseeable. Therefore, having selected a controller server, we recommend you install Debian - if you want to get going fast, you will install Debian 12 on your "control node" (controller).
The Debian documentation is somewhat convoluted, so our recommended quick setup instructions for Debian are as follows:
- Download the Fedora Media Writer for your platform:
- Download the Debian 12 ISO file (click the ISO link in the first line of the page)
- Open Fedora Media Writer and select "Select .iso file", then click Next
- Click the Select button and pick your downloaded Debian ISO file
- IMPORTANT, this process will completely wipe your USB key! - plug in a USB key that you don't mind being wiped!
- Click Write
After a few minutes the Fedora Media Writer will tell you it has completed creating your bootable USB key. You can select this USB key as the boot device on any physical or virtual machine you decide to use as your controller, and you will find the Debian 12 installer pops up and leads you through the process.
If you want to use a container as your controller, pull the latest Debian 12 image from Docker Hub. This command should always get you the latest Debian 12 image:
docker pull debian:12Most major cloud providers will have a Debian 12 base image for their servers, simply select the official Debian 12 image as the starting image for your cloud server and it should contain everything you need to continue.
Once you have your Debian 12 machine up and running, either SSH in or, if using a desktop environment, open a Terminal by pressing the "Super" (aka Windows) key, typing Terminal and pressing enter. Then run the following commands to download and execute our one-time install script for ce-provision. Ultimately, for more advanced usage you will need somewhere to keep your infrastructure code, which is why the script can optionally install GitLab Community Edition for you. The options are as follows:
curl -LO https://raw.githubusercontent.com/codeenigma/ce-provision/2.x/install.sh
chmod +x ./install.sh
sudo ./install.sh -h # for usage information
# Default installation (ce-provision only)
sudo ./install.sh
# Installation with GitLab CE using a self-signed SSL certificate
sudo ./install.sh --gitlab gitlab.example.com
# Installation with GitLab CE using a LetsEncrypt SSL certificate (requires DNS to be set up in advance)
sudo ./install.sh --letsencrypt --gitlab gitlab.example.com
# Same as above, but with AWS CLI support
sudo ./install.sh --letsencrypt --gitlab gitlab.example.com --awsOnce 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:
- Switch to the controller user with
sudo su -l controller(if you used the--userflag on installation then obviously whatever user you chose) - Move to the ce-provision directory with
cd ~/ce-provision - Make a directory for your playbooks in your config directory with
mkdir config/plays - With your favourite text editor, open a new playbook file, e.g.
vim config/plays/local-webserver.yml - 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- Run ce-provision with:
./scripts/provision.sh \
--repo none \
--branch none \
--playbook config/plays/local-webserver.yml \
--python-interpreter $HOME/ce-python/bin/python3You 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.
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: _exitIn 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:
- Ensure example1.acme.com (the target) is up and running and has a correct DNS entry the controller can use
- 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)
- On the controller, edit
ce-provision/config/hosts/hosts.ymland add this:
acme:
hosts:
example.acme.com:- 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- Run ce-provision again but without
--python-interpreterbecause 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.
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)
TODO
TODO
TODO