Your first Ansible playbook: install nginx and publish a page

This tutorial takes you from an empty folder to a web server configured by Ansible. It targets Debian or Ubuntu hosts (it uses the apt module). You need Ansible on your machine, SSH key access to the servers and a user that can use sudo.

Step 1: create the inventory

Make a project folder and an inventory file named inventory.ini. Replace the example names and addresses with your own servers.

[web]
web1.example.com ansible_host=192.0.2.10
web2.example.com ansible_host=192.0.2.11

[web:vars]
ansible_user=admin

ansible_host is the address to connect to, ansible_user the SSH login. Check that Ansible can reach every host:

ansible web -i inventory.ini -m ping

Each host should answer SUCCESS with "ping": "pong". If you see UNREACHABLE!, fix SSH first (see the separate fix entry for that error).

Step 2: write the playbook

Save this as site.yml:

---
- name: Install nginx and publish a home page
  hosts: web
  become: true
  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true
        cache_valid_time: 3600

    - name: Make sure nginx is running and starts at boot
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

    - name: Publish a simple home page
      ansible.builtin.copy:
        content: "<h1>Deployed by Ansible</h1>\n"
        dest: /var/www/html/index.html
        owner: root
        group: root
        mode: "0644"

• hosts: web runs the play on the web group from the inventory.
• become: true runs the tasks with sudo, because installing packages needs root.
• update_cache with cache_valid_time: 3600 refreshes the apt index only if it is older than an hour.
• enabled: true makes nginx start automatically after a reboot.
• On Debian and Ubuntu the default nginx site serves /var/www/html, so the copied index.html becomes the home page.

Step 3: dry run, then apply

1. Check the YAML: ansible-playbook -i inventory.ini site.yml --syntax-check
2. Preview without changing anything: ansible-playbook -i inventory.ini site.yml --check. In check mode some tasks cannot know their final result (nginx is not installed yet, so the service task may fail); that is expected on a first run.
3. Apply it: ansible-playbook -i inventory.ini site.yml. Add -K (--ask-become-pass) if sudo asks for a password on the servers.

At the end Ansible prints a PLAY RECAP line per host with counters such as ok, changed, unreachable and failed.

Step 4: verify and run it again

curl http://192.0.2.10/
ansible-playbook -i inventory.ini site.yml

The page should show “Deployed by Ansible”. The second playbook run should report changed=0 for every host: the package is present, the service is running and the file already has the right content, so nothing is touched. This is idempotency, and it is why you can safely re-run playbooks.

Where to go next

Move hard-coded values into variables, render the nginx configuration from a template and reload nginx only when it changes. Those are the next steps: variables, templates and handlers.

Official documentation

• Building an inventory
• Ansible playbooks
• ansible.builtin.apt module