paul/ansible-role-homepage
Watch
1
0
Fork
You've already forked ansible-role-homepage
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Ansible role: homepage dashboard via Docker Compose
1 commit 1 branch 0 tags 6.2 KiB
  • Jinja 100%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Paul Provost 19d059c5f0 Initial homepage role, modelled on the atuin role 
Docker Compose deployment of gethomepage/homepage with services,
widgets, bookmarks and settings generated from variables, and an
optional extra CA trusted via NODE_EXTRA_CA_CERTS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 14:35:27 -04:00
defaults Initial homepage role, modelled on the atuin role 2026-10-28 14:35:27 -04:00
handlers Initial homepage role, modelled on the atuin role 2026-10-28 14:35:27 -04:00
meta Initial homepage role, modelled on the atuin role 2026-10-28 14:35:27 -04:00
tasks Initial homepage role, modelled on the atuin role 2026-10-28 14:35:27 -04:00
templates Initial homepage role, modelled on the atuin role 2026-10-28 14:35:27 -04:00
README.md Initial homepage role, modelled on the atuin role 2026-10-28 14:35:27 -04:00

README.md

homepage

Deploy a homepage dashboard via Docker Compose, with its configuration (services, widgets, bookmarks, settings) generated from Ansible variables. Based on the official compose reference.

Requirements

  • Docker with the compose plugin already installed (e.g. via geerlingguy.docker).
  • community.docker collection (needs the python3-docker apt package's bindings - this role installs it).

Role Variables

Variable Default Description
homepage_version v2.7.0 ghcr.io/gethomepage/homepage image tag (with v prefix).
homepage_bind_address 0.0.0.0 Host address the port is published on.
homepage_port 3000 Host port mapped to homepage.
homepage_allowed_hosts "" (required) HOMEPAGE_ALLOWED_HOSTS: comma-separated Host headers homepage answers, e.g. home.example.com.
homepage_base_dir ~/local/homepage Compose file, CA certificate and config dir.
homepage_config_dir <base>/config Mounted at /app/config.
homepage_uid / homepage_gid connecting user's PUID/PGID the container runs as; own the config dir.
homepage_ca_cert_src "" PEM file on the control machine trusted via NODE_EXTRA_CA_CERTS (e.g. a private CA, for siteMonitor on internal-TLS sites).
homepage_title Homepage Page title.
homepage_settings {} settings.yaml, merged over { title: homepage_title }.
homepage_services [] services.yaml, verbatim.
homepage_widgets [] widgets.yaml, verbatim.
homepage_bookmarks [] bookmarks.yaml, verbatim.
homepage_tz Etc/UTC Container timezone.
homepage_restart_policy unless-stopped Compose restart policy.

docker.yaml is written empty: the role doesn't mount the Docker socket.

Tags

  • config, container, verify - the usual run.
  • upgrade - pull the image (after bumping homepage_version) and recreate.

Example Playbook

- hosts: razorback
  vars:
    ansible_python_interpreter: /usr/bin/python3
    homepage_allowed_hosts: home.example.com
    homepage_services:
      - Media:
          - Jellyfin:
              href: https://media.example.com
              icon: jellyfin.png
              siteMonitor: https://media.example.com
  roles:
    - role: homepage

Notes

  • Homepage reloads config files on change; only compose or CA changes restart the container.
  • Homepage's own authentication (v2+) is left off; serve it behind a reverse proxy that limits who can reach it.
  • siteMonitor and widget requests come from the container, so the host's DNS and the proxy's allow lists apply to them.