Quick start guide

For users who want to try the role quickly, this guide provides an example of how to install and configure lighttpd on a single FreeBSD host. The procedure is generic and can be easily modified to install and configure other applications on other systems. See examples in the directory contrib. The control node of this example is Linux, and the user running the playbook on the controller is a member of the group adm.

Install the role, collections, and linter 

Install the role vbotka.config_light

shell> ansible-galaxy role install vbotka.config_light

Install the collections if necessary

shell> ansible-galaxy collection install ansible.posix
shell> ansible-galaxy collection install community.general
shell> ansible-galaxy collection install vbotka.freebsd

Install yamllint to use the default validation of the created handlers and assembled data. See the variables cl_assemble_validate and cl_handlers_validate in defaults/main.yml. Optionally, use ansible-lint or disable the validation by clearing the variables
```
cl_assemble_validate: ''
cl_handlers_validate: ''
```

Create project 

Create a project

shell> tree .
.
├── conf-light
│   ├── files.d
│   │   ├── lighttpd-index.yml
│   │   ├── lighttpd-lighttpdconf.yml
│   │   └── lighttpd-rcconf.yml
│   ├── handlers.d
│   │   └── lighttpd-freebsd.yml
│   ├── packages.d
│   │   └── lighttpd.yml
│   ├── services.d
│   │   └── lighttpd.yml
│   └── states.d
│       └── lighttpd-server-document-root.yml
├── group_vars
│   └── all
│       ├── cl-common.yml
│       ├── cl-lighttpd.yml
│       └── common.yml
└── pb.yml

Create the playbook pb.yml for single host srv.example.com (1) and the role vbotka.config_light (10)

pb.yml

- hosts: srv.example.com
  gather_facts: true
  connection: ssh
  remote_user: admin
  become: true
  become_user: root
  become_method: sudo

  roles:
    - vbotka.config_light

Configure role 

Create common variables

group_vars/all/common.yml

freebsd_install_method: packages
freebsd_pkgng_use_globs: false

Configure the role. To speed up the execution, set the control-flow variables (1-3) to false and disable some steps. Enable these steps selectively when needed. The configuration data will be stored in the directory conf-light (8) in the current directory of the playbook. Set the ownership and permissions of the directories on the control node so that the user who is running the playbook will be able to both read and write the files, and create the directories cl_dird, cl_dira, and “{{ role_path }}/handlers”

host_vars/srv.example.com/cl-common.yml

cl_sanity: false
cl_setup: false
cl_install: false
cl_backup: true

cl_dird_group: adm
cl_dird_dmode: "0770"
cl_dird: "{{ playbook_dir }}/conf-light"

cl_dira_group: adm
cl_dira_dmode: "0770"
cl_dira_fmode: "0660"

cl_handlers_dir_group: adm

Note

The configuration data will be assembled into the directory cl_dira
The default value of cl_dira is "{{ cl_dird }}/assemble"

Configure lighttpd 

Configure the application. Start the server (1), run the server at boot (2), and configure two files (4,17)

host_vars/srv.example.com/cl-lighttpd.yml

cl_service_lighttpd_enable: true
cl_service_lighttpd_state: start

# /usr/local/etc/lighttpd/lighttpd.conf
cl_lighttpd_server_port: '80'
cl_lighttpd_server_useipv6: disable
cl_lighttpd_server_username: www
cl_lighttpd_server_groupname: www
cl_lighttpd_server_document_root: /usr/local/www/lighttpd
cl_lighttpd_lighttpdconf_dict:
  - {key: server.port, value: '"{{ cl_lighttpd_server_port }}"'}
  - {key: server.use-ipv6, value: '"{{ cl_lighttpd_server_useipv6 }}"'}
  - {key: server.username, value: '"{{ cl_lighttpd_server_username }}"'}
  - {key: server.groupname, value: '"{{ cl_lighttpd_server_groupname }}"'}
  - {key: server.document-root, value: '"{{ cl_lighttpd_server_document_root }}"'}

# /etc/rc.conf
cl_lighttpd_rcconf_lighttpd_enable: 'YES'
cl_lighttpd_rcconf_dict:
  - {key: lighttpd_enable, value: '"{{ cl_lighttpd_rcconf_lighttpd_enable }}"'}

Create configuration data in the directory conf-light/

conf-light/files.d/lighttpd-index.yml

lighttpd-index:
  path: "{{ cl_lighttpd_server_document_root }}/index.html"
  owner: "{{ cl_lighttpd_server_username }}"
  group: "{{ cl_lighttpd_server_groupname }}"
  create: true
  mode: "0644"
  lines:
    - line: Lighttpd works !

conf-light/files.d/lighttpd-lighttpdconf.yml

lighttpd-lighttpdconf:
  path: /usr/local/etc/lighttpd/lighttpd.conf
  create: true
  owner: root
  group: wheel
  mode: '0644'
  assignment: ' = '
  dict: "{{ cl_lighttpd_lighttpdconf_dict }}"
  handlers:
    - reload lighttpd

conf-light/files.d/lighttpd-rcconf.yml

lighttpd_rcconf:
  path: /etc/rc.conf
  create: true
  owner: root
  group: wheel
  mode: '0644'
  assignment: '='
  dict: "{{ cl_lighttpd_rcconf_dict }}"
  handlers:
    - reload lighttpd

conf-light/handlers.d/lighttpd-freebsd.yml

lighttpd_freebsd:

  template: handlers-auto3.yml.j2
  handlers:

    - handler: Start lighttpd
      listen: start lighttpd
      module: vbotka.freebsd.service
      params:
        - 'script: lighttpd'
        - 'command: start'

    - handler: Stop lighttpd
      listen: stop lighttpd
      module: vbotka.freebsd.service
      params:
        - 'script: lighttpd'
        - 'command: stop'

    - handler: Reload lighttpd
      listen: reload lighttpd
      module: vbotka.freebsd.service
      params:
        - 'script: lighttpd'
        - 'command: reload'
      conditions:
        - '- cl_service_lighttpd_enable | bool'

    - handler: Restart lighttpd
      listen: restart lighttpd
      module: vbotka.freebsd.service
      params:
        - 'script: lighttpd'
        - 'command: restart'
      conditions:
        - '- cl_service_lighttpd_enable | bool'

    - handler: Lighttpd check
      listen: lighttpd check
      module: ansible.builtin.command
      params:
        - 'cmd: /usr/local/sbin/lighttpd -t'

conf-light/packages.d/lighttpd.yml

lighttpd:
  module: pkgng
  name:
    - www/lighttpd

conf-light/services.d/lighttpd.yml

lighttpd:
  name: lighttpd
  state: "{{ cl_service_lighttpd_state }}"
  enabled: "{{ cl_service_lighttpd_enable }}"

conf-light/states.d/lighttpd-server-document-root.yml

lighttpd_server_document_root:
  state: directory
  path: "{{ cl_lighttpd_server_document_root }}"
  owner: "{{ cl_lighttpd_server_username }}"
  group: "{{ cl_lighttpd_server_groupname }}"
  mode: '0750'

Setup 

Select and enable setup. This command will assemble the configuration data and create handlers on the control node. Take a look at the directory conf-light/assemble/ what files were created. Also, look at the directory roles/vbotka.config_light/handlers, what handlers were created
```
shell> ansible-playbook pb.yml -t cl_setup -e cl_setup=true
```
Note
- The tasks vars are tagged always.
- The tasks setup and sanity are enabled by default cl_setup=true, cl_sanity=true.

Enable and test sanity

shell> ansible-playbook pb.yml -t cl_sanity -e cl_sanity=true

Display variables

shell> ansible-playbook pb.yml -t cl_debug -e cl_debug=true

Run the play 

Install packages

shell> ansible-playbook pb.yml -t cl_packages -e cl_install=true

Set files state

shell> ansible-playbook pb.yml -t cl_states

Create and modify files

shell> ansible-playbook pb.yml -t cl_files

Configure services

shell> ansible-playbook pb.yml -t cl_services

Hint

If you know what you are doing skip the above selection of particular tags and run the complete role at once

shell> ansible-playbook pb.yml -e cl_setup=true -e cl_sanity=true -e cl_install=true

Results 

Open the page in a browser http://srv.example.com/. The content should be
```
Lighttpd works!
```

Quick start guide

Install the role, collections, and linter

Create project

Configure role

Configure lighttpd

Setup

Run the play

Results