# Getting Started with Ansible: A Practical Guide
[Ansible](https://github.com/ansible/ansible) is a powerful yet straightforward automation tool that can save you
countless hours of repetitive system administration tasks.
In this guide, you'll learn the essentials of Ansible and complete a practical
project by setting up a web server automatically.
By the end of this article, you'll have hands-on experience with Ansible's core
concepts and a working web server deployment you can build upon for your own
projects.
## What is Ansible?
Ansible is an open-source automation platform that simplifies configuration
management, application deployment, and task automation.
Unlike some other automation tools, Ansible doesn't require special software to
be installed on the machines you want to manage. Instead, it communicates with
your systems using SSH, making it significantly easier to get started.
At its core, Ansible works by sending instructions from a control machine (your
computer) to target machines (servers you want to manage). These instructions,
written in YAML, tell the target machines exactly what state they should be
in—what software should be installed, how services should be configured, and so
on.
### Why use Ansible?
The beauty of Ansible lies in its simplicity. Ansible is agentless, meaning you
don't need to install and maintain client software on your servers. It uses YAML
syntax, which is human-readable and easy to learn even for beginners.
Ansible operations are idempotent, so you can run the same instructions multiple
times without causing problems—it only makes changes when needed.
Additionally, Ansible comes with hundreds of built-in modules for managing
various systems and services, making it versatile for different automation
needs.
## Setting up your environment
Before you can start automating, you'll need to install Ansible on your control
machine (the computer from which you'll run your commands).
I'll focus on installation for Linux and macOS, as these are the most common
platforms for Ansible controllers.
For Ubuntu/Debian systems:
```command
sudo apt update
```
```command
sudo apt install ansible
```
For macOS (using Homebrew):
```command
brew install ansible
```
### Verifying your installation
Once installed, verify that Ansible is working correctly by checking its
version:
```command
ansible --version
```
You should see output similar to this:
```text
[output]
ansible [core 2.16.14]
config file = /etc/ansible/ansible.cfg
configured module search path = ['/home/ayo/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
ansible python module location = /usr/lib/python3.13/site-packages/ansible
ansible collection location = /home/ayo/.ansible/collections:/usr/share/ansible/collections
executable location = /usr/bin/ansible
python version = 3.13.2 (main, Feb 4 2025, 00:00:00) [GCC 14.2.1 20250110 (Red Hat 14.2.1-7)] (/usr/bin/python3)
jinja version = 3.1.5
libyaml = True
```
[ad-logs]
## Understanding the inventory
The inventory is simply a list of systems that Ansible will manage. While
Ansible supports dynamic inventories that can pull server information from cloud
providers or other sources, we'll start with a basic static inventory file.
### Creating a simple inventory file
Create a new file named `inventory.ini` in your working directory:
```ini
[webservers]
webserver1 ansible_host=192.168.1.10
[database]
db1 ansible_host=192.168.1.11
[all:vars]
ansible_user=your_ssh_user
ansible_ssh_private_key_file=/path/to/your/private_key
```
This inventory defines a group called `webservers` containing one server with IP
192.168.1.10, a group called `database` with one server, and variables that
apply to all servers, specifying how to connect via SSH.
For beginners, it's perfectly fine to start with just one server. You can even
use localhost for testing:
```ini
[webservers]
localhost ansible_connection=local
```
### Testing connectivity
Let's verify that Ansible can communicate with your servers using the `ping`
module:
```command
ansible webservers -i inventory.ini -m ping
```
If successful, you should see:
```text
[output]
localhost | SUCCESS => {
"ansible_facts": {
"discovered_interpreter_python": "/usr/bin/python3"
},
"changed": false,
"ping": "pong"
}
```
If you see "pong" in the response, your connection is working correctly. If you
encounter errors, check your SSH configuration and make sure you can manually
SSH into the target servers.
## Running ad-hoc commands
Before diving into playbooks, let's explore ad-hoc commands. These are one-liner
tasks that you might need to perform quickly across multiple servers.
### Basic command structure
Ad-hoc commands follow this structure:
```command
ansible [group] -i [inventory_file] -m [module] -a "[module arguments]"
```
Let's try some useful ad-hoc commands, starting with checking system
information:
```command
ansible webservers -i inventory.ini -m gather_facts
```
```json
[output]
localhost | SUCCESS => {
"ansible_facts": {
. . .
},
"changed": false,
"deprecations": [],
"warnings": []
}
```
This command returns detailed information about your target servers, including
operating system, memory, and network configuration.
Another command ad-hoc command is one that installs a package. On Ubuntu/Debian,
use:
```command
ansible webservers -i inventory.ini -m apt -a "name=nginx state=present" --become
```
This installs Nginx on your webservers. The `--become` flag tells Ansible to use
privilege escalation (`sudo`).
Finally, you can create a file on your target servers with:
```command
ansible webservers -i inventory.ini -m copy -a "content='Hello from Ansible' dest=/tmp/ansible_test.txt"
```
```json
[output]
localhost | CHANGED => {
"ansible_facts": {
"discovered_interpreter_python": "/usr/bin/python3"
},
"changed": true,
"checksum": "5332d55f8fbdb22d9875ff5650211ed9630b1d68",
"dest": "/tmp/ansible_test.txt",
"gid": 1000,
"group": "ayo",
"md5sum": "4ed8eb0db4371dcd7ca9d773455bdd82",
"mode": "0644",
"owner": "ayo",
"secontext": "unconfined_u:object_r:user_home_t:s0",
"size": 18,
"src": "/home/ayo/.ansible/tmp/ansible-tmp-1742183730.0935683-2183216-224482429836629/source",
"state": "file",
"uid": 1000
}
```
This creates a file with the specified content in the `/tmp` directory.
Ad-hoc commands are great for quick tasks, but for repeatable operations,
playbooks are the way to go so lets explore that next.
## Writing your first playbook
Playbooks are Ansible's configuration, deployment, and orchestration language.
They describe a policy you want your systems to enforce, using a simple,
declarative format.
To get started, create a file named `webserver.yml`:
```yaml
[label webserver.yaml]
- name: Setup web server
hosts: webservers
become: yes
tasks:
- name: Update apt cache
apt:
update_cache: yes
cache_valid_time: 3600
- name: Install packages
apt:
name:
- nginx
- ufw
state: present
- name: Ensure Nginx is running
service:
name: nginx
state: started
enabled: yes
```
This simple playbook targets the `webservers` group from your inventory,
requests privilege escalation (`sudo`), updates the apt cache if it hasn't been
updated in the last hour, installs Nginx, and makes sure Nginx is running and
set to start on boot.
Once saved, execute your playbook with:
```command
ansible-playbook -i inventory.ini webserver.yaml
```
You should see output showing the execution of each task:
```text
[output]
PLAY [Setup web server] ***********************************************
TASK [Gathering Facts] ***********************************************
ok: [webserver1]
TASK [Update apt cache] **********************************************
ok: [webserver1]
TASK [Install Nginx] ************************************************
changed: [webserver1]
TASK [Ensure Nginx is running] **************************************
changed: [webserver1]
PLAY RECAP **********************************************************
webserver1 : ok=4 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
```
Congratulations! You've just automated the installation and configuration of a
web server. If you run the playbook again, you'll notice most tasks report as
"ok" rather than "changed"—this is Ansible's idempotence at work. It only makes
changes when needed.
## Expanding your web server project
Now let's enhance our web server by adding a custom homepage and configuring
firewall rules.
First, let's create a templates directory and a template for our custom
homepage:
```command
mkdir templates
```
Create `templates/index.html.j2`:
```html
[label templates/index.html.j2]
Welcome to {{ ansible_hostname }}
Hello from {{ ansible_hostname }}
This server was configured automatically using Ansible on {{ ansible_date_time.date }}.
```
Now, update your playbook to use this template:
```yaml
[label webserver.yaml]
- name: Setup web server
hosts: webservers
become: yes
tasks:
- name: Update apt cache
apt:
update_cache: yes
cache_valid_time: 3600
- name: Install packages
apt:
name:
- nginx
- ufw
state: present
[highlight]
- name: Create custom index page
template:
src: templates/index.html.j2
dest: /var/www/html/index.html
owner: www-data
group: www-data
mode: '0644'
notify: Reload Nginx
[/highlight]
- name: Ensure Nginx is running
service:
name: nginx
state: started
enabled: yes
[highlight]
handlers:
- name: Reload Nginx
service:
name: nginx
state: reloaded
[/highlight]
```
The template module uses Jinja2 templating to replace variables in your template
with actual values. The variables with `ansible_` prefix are gathered by Ansible
automatically as facts about the system.
Also notice the introduction of a handler. Handlers are special tasks that only
run when notified by another task, typically used for restarting services when
their configuration changes.
### Configuring firewall rules
Let's add firewall configuration to our playbook to allow HTTP traffic:
```yaml
[label webserver.yaml]
- name: Setup web server
hosts: webservers
become: yes
tasks:
- name: Update apt cache
apt:
update_cache: yes
cache_valid_time: 3600
- name: Install packages
apt:
name:
- nginx
- ufw
state: present
- name: Create custom index page
template:
src: templates/index.html.j2
dest: /var/www/html/index.html
owner: www-data
group: www-data
mode: '0644'
notify: Reload Nginx
[highlight]
- name: Allow HTTP traffic
ufw:
rule: allow
name: Nginx Full
state: enabled
- name: Enable UFW
ufw:
state: enabled
policy: deny
[/highlight]
- name: Ensure Nginx is running
service:
name: nginx
state: started
enabled: yes
handlers:
- name: Reload Nginx
service:
name: nginx
state: reloaded
```
This updated playbook installs both Nginx and UFW (Uncomplicated Firewall),
creates a custom index page, configures the firewall to allow HTTP and HTTPS
traffic, enables the firewall with a default deny policy, and ensures Nginx is
running.
### Testing your completed web server
Run your updated playbook:
```command
ansible-playbook -i inventory.ini webserver.yml
```
After the playbook completes, open a web browser and navigate to your server's
IP address. You should see your custom homepage with the server's information.
If everything works correctly, you've successfully used Ansible to install
necessary packages, configure a web server, deploy custom content, and set up
security rules.
## Troubleshooting common issues
Even with a tool as straightforward as Ansible, you might encounter some issues.
Here are some common problems and how to solve them:
### Connection problems
If Ansible can't connect to your servers, check SSH connectivity by making sure
you can manually SSH into the target servers. Verify hostnames and IP addresses
in your inventory file, and ensure your SSH key or password authentication is
working.
For more detailed connection debugging, add the `-vvv` flag:
```command
ansible webservers -i inventory.ini -m ping -vvv
```
### Permission errors
If tasks fail due to permission issues, check that the `become: yes` directive
is included in your playbook. Ensure your user has sudo privileges on the target
system. For specific files, check ownership and permissions.
### Syntax mistakes
YAML is sensitive to indentation. If you get syntax errors, use a YAML linter or
editor with YAML support. Check your indentation (spaces, not tabs) and verify
that all colons, dashes, and quotes are correctly placed.
You can validate your playbook syntax without running it:
```command
ansible-playbook -i inventory.ini webserver.yml --syntax-check
```
## Final thoughts
Ansible makes automation accessible even to beginners. Through this guide,
you've learned how to install and configure Ansible, create an inventory of
managed systems, run one-off commands across multiple servers, write playbooks
for repeatable configurations, and deploy a working web server with custom
content and security settings.
The skills you've gained provide a foundation for more complex automation tasks.
To further develop your Ansible skills, explore
[Ansible's official documentation](https://docs.ansible.com/) and experiment
with different modules from the
[module library](https://docs.ansible.com/ansible/2.9/modules/modules_by_category.html).
Think about repetitive tasks in your workflow that could be automated. You might
want to deploy your favorite application stack, set up regular backups,
configure monitoring tools, or standardize security settings across servers.
By investing time in learning Ansible, you're taking a significant step toward
more efficient and consistent system administration. Happy automating!