# 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