Nathan
ac6e68e301
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)
99 lines
3.2 KiB
Markdown
99 lines
3.2 KiB
Markdown
# 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
|
|
|
|
```yaml
|
|
- 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:
|
|
1. Provisions an LXC container on Proxmox
|
|
2. 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
|