Nathan ac6e68e301 docs(ansible): add comprehensive documentation for openapply_app role

Complete role documentation suite per Ansible Galaxy and homelab standards:
- Add role README.md with variable tables, usage examples, and deployment notes
- Add meta/main.yml for Galaxy metadata and collection dependencies
- Add OPENAPPLY-VAULT-REFERENCE.md with vault setup and Proxmox token guide
- Add OPENAPPLY-IMPLEMENTATION-REPORT.md with architecture, validation, and handoff details

Context: Completes the OpenApply LXC deployment implementation from session plan.
This documentation enables users to configure vault secrets, understand role variables,
and execute the two-tier Proxmox provisioning workflow.

Ref: Session plan at /memories/session/plan.md (Phases 1-6 complete)

2026-04-17 19:29:13 -04:00

3.2 KiB

Raw Blame History

openapply_app

Ansible role to deploy the OpenApply application stack (Vue.js/Astro/Firebase) to an Ubuntu LXC guest.

Description

This role configures an Ubuntu 22.04/24.04 LXC container to run the OpenApply web application in production mode. It handles:

Node.js 20+ runtime installation via NodeSource
pnpm package manager setup
Firebase CLI installation (optional)
UFW firewall configuration (production ports only: 22, 80, 443)
Git-based source deployment
Systemd service configuration and lifecycle management
Application build process for Astro and SPA components
HTTP health validation

Requirements

Target OS: Ubuntu 22.04 (Jammy) or 24.04 (Noble)
Minimum Ansible: 2.16
Collections:
- community.general >= 8.0.0
- ansible.posix >= 1.5.0

Role Variables

Application Settings

Variable	Default	Description
`openapply_app_repo_url`	`https://github.com/sergeykhval/openapply.git`	Git repository URL
`openapply_app_repo_version`	`main`	Git branch/tag/commit
`openapply_app_root`	`/opt/openapply`	Application install path
`openapply_app_service_name`	`openapply`	Systemd service name
`openapply_app_service_user`	`openapply`	Service runtime user
`openapply_app_service_group`	`openapply`	Service runtime group
`openapply_app_service_port`	`80`	HTTP listen port

Runtime Configuration

Variable	Default	Description
`openapply_app_node_major`	`"20"`	Node.js major version
`openapply_app_install_firebase_cli`	`true`	Install Firebase CLI globally
`openapply_app_build_subdirs`	`["astro", "spa"]`	Subdirectories to build
`openapply_app_force_rebuild`	`false`	Force rebuild on every run

Network & Security

Variable	Default	Description
`openapply_app_enable_firewall`	`true`	Enable UFW firewall
`openapply_app_allowed_tcp_ports`	`[22, 80, 443]`	Allowed TCP ports

Secrets

Variable	Default	Description
`openapply_app_firebase_token`	`{{ vault_openapply_firebase_token \| default('') }}`	Firebase deployment token

Dependencies

None.

Example Playbook

- name: Deploy OpenApply application
  hosts: openapply_lxc_guest
  become: true
  roles:
    - role: openapply_app
      vars:
        openapply_app_repo_version: "v1.2.3"
        openapply_app_service_port: 8080

Example with Proxmox Provisioning

See playbooks/deploy-openapply.yml for a complete two-tier workflow that:

Provisions an LXC container on Proxmox
Deploys and configures OpenApply inside the guest

License

MIT

Author

Created by FrankGPT for the homelab infrastructure automation project.

Notes

Production-only mode: Dev ports (3000, 5173) are not exposed by default
Git clone strategy: Application code is cloned fresh on first run, then updated on subsequent runs
Build idempotency: Builds are triggered only when repo changes or openapply_app_force_rebuild is set
Systemd lifecycle: Service is managed via systemd with automatic restart on failure

3.2 KiB Raw Blame History