Home Server Role Creator

• Pre-development checklist
• Role structure checklist
• Variable definition checklist
• Task implementation checklist
• Integration checklists (firewall, NGINX, SELinux, DNS)
• Pre-deployment checklist
• Post-deployment verification checklist
• Troubleshooting guides

Load these reference files when detailed examples or comprehensive checklists are needed.

Role Creation Workflow

Follow this workflow for every new service:

1. Planning Phase

Determine Installation Method:

Is the service containerized?
├─ Yes → Use Podman Quadlet pattern (see references/role-examples.md: Immich)
└─ No → Is it available in DNF/RPM repositories?
    ├─ Yes → Use Package installation (see references/role-examples.md: Jellyfin)
    └─ No → Use Binary download/installation (see references/role-examples.md: FileBrowser)

Identify Required Integrations:

• Web interface? → Needs NGINX reverse proxy
• Needs firewall port access? → Firewall configuration
• Custom storage locations? → SELinux contexts required
• Subdomain access? → DNS rewrite in AdGuard

2. Directory Setup

Create the role directory structure:

mkdir -p roles/[service_name]/{defaults,tasks,handlers,templates,meta}

Required directories:

• defaults/ - Default variables (always created)
• tasks/ - Task files (always created)
• handlers/ - Event handlers (always created)
• templates/ - Jinja2 templates (if service needs config files or systemd units)
• meta/ - Role metadata (always created)

3. Core Implementation

Step 3.1: Create defaults/main.yml

Define all configurable variables following this pattern:

---
# Default variables for [Service] role

# Service user configuration
service_user: ndelucca
service_group: ndelucca

# Directory configuration
service_base_dir: /opt/service  # or /srv/service
service_working_dir: "{{ service_base_dir }}/data"
service_config_dir: "{{ service_base_dir }}/config"

# Service configuration
service_name: service
service_enabled: true
service_state: started

# Network configuration
service_bind_address: 127.0.0.1  # ALWAYS 127.0.0.1 for web services
service_port: 8080

# Firewall settings
service_firewall_enabled: false  # false if behind NGINX
service_firewall_zone: FedoraServer

# SELinux configuration
service_manage_selinux: true

See references/checklists.md for complete variable definition checklist.

Step 3.2: Create tasks/main.yml

Orchestration file that imports modular task files:

---
# Main entry point for [Service] role

- name: Include preflight checks
  ansible.builtin.import_tasks: preflight.yml
  tags: ['service', 'preflight']

- name: Install [Service]
  ansible.builtin.import_tasks: install.yml
  tags: ['service', 'install']

- name: Configure [Service] application
  ansible.builtin.import_tasks: configure.yml
  tags: ['service', 'configure']
  when: service_use_config_file | bool

- name: Configure systemd service
  ansible.builtin.import_tasks: service.yml
  tags: ['service', 'systemd']

- name: Configure SELinux
  ansible.builtin.import_tasks: selinux.yml
  tags: ['service', 'selinux']
  when: service_manage_selinux | bool

Step 3.3: Task Files

Create these task files based on service type:

Always Required:

• preflight.yml - OS verification, directory creation
• install.yml - Service installation (method varies by type)
• service.yml - Systemd service management
• selinux.yml - SELinux contexts and ports

Conditional:

• configure.yml - If service needs configuration files
• repository.yml - If package needs external repository
• quadlet.yml - If using Podman containers

For detailed implementation examples, see references/role-examples.md.

Step 3.4: Create handlers/main.yml

Standard Services:

---
# Handlers for [Service] role

- name: daemon-reload
  ansible.builtin.systemd:
    daemon_reload: true
  become: true

- name: restart service
  ansible.builtin.systemd:
    name: "{{ service_name }}"
    state: restarted
  become: true

- name: apply selinux context
  ansible.builtin.command: "restorecon -Rv {{ item }}"
  become: true
  loop:
    - "{{ service_install_dir }}/service"
    - "{{ service_working_dir }}"
  changed_when: false

Rootless Podman Services:

---
# Handlers for rootless Podman service

- name: daemon-reload-user
  ansible.builtin.systemd:
    daemon_reload: true
    scope: user
  become: true
  become_user: "{{ service_user }}"
  environment:
    XDG_RUNTIME_DIR: "/run/user/{{ service_uid }}"

- name: restart service-pod
  ansible.builtin.systemd:
    name: "{{ service_name }}"
    state: restarted
    scope: user
  become: true
  become_user: "{{ service_user }}"
  environment:
    XDG_RUNTIME_DIR: "/run/user/{{ service_uid }}"

Step 3.5: Create meta/main.yml

---
galaxy_info:
  author: Naza
  description: Install and configure [Service] on Fedora
  license: MIT
  min_ansible_version: '2.13'
  platforms:
    - name: Fedora
      versions:
        - all