ilia/ansible
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
ansible/docs/guides/app_stack_proxmox.md
ilia 0a937fd1b4
All checks were successful
CI / skip-ci-check (push) Successful in 1m23s
Details
CI / lint-and-test (push) Successful in 1m27s
Details
CI / ansible-validation (push) Successful in 2m59s
Details
CI / secret-scanning (push) Successful in 1m24s
Details
CI / dependency-scan (push) Successful in 1m29s
Details
CI / sast-scan (push) Successful in 2m41s
Details
CI / license-check (push) Successful in 1m27s
Details
CI / vault-check (push) Successful in 2m29s
Details
CI / playbook-test (push) Successful in 2m38s
Details
CI / container-scan (push) Successful in 1m56s
Details
CI / sonar-analysis (push) Successful in 2m33s
Details
CI / workflow-summary (push) Successful in 1m21s
Details
feat(app_setup): Improves deployment reliability for app projects and adds support for mirrormatch deployment with Prisma/Next.js requirements. (#5) 
## Summary

Improves deployment reliability for app projects and adds support for mirrormatch deployment with Prisma/Next.js requirements.

## Changes

### Core Improvements (affects all app projects)

1. **Deploy Script (`deploy_app.sh.j2`)**
   - Fixed clone logic to handle non-git directories gracefully
   - Preserves `.env.*` files during repository clone
   - Uses temporary directory for initial clone to avoid permission issues
   - Added `sudo` to systemctl restart commands (appuser needs sudo for service management)

2. **Environment Template (`env.j2`)**
   - Removed comment lines to prevent `xargs` errors when sourcing env files
   - Cleaner, more reliable env file format

3. **App Setup Role (`app_setup/tasks/main.yml`)**
   - Added initial deploy task to run deploy script during first configure
   - Ensures app is fully deployed before systemd service starts

4. **Configure Playbook (`configure_app.yml`)**
   - Fixed migrate command precedence: checks `env_def.backend_migrate_cmd` first
   - Allows per-environment override of migrate commands (e.g., `db:push` for dev/qa)

### Mirrormatch-Specific Configuration

- Added `mirrormatch` project definition with dev/qa/prod environments
- Configured `backend_migrate_cmd: "npm run db:push"` for dev/qa (no shadow DB needed)
- Added `backend_seed_cmd` support for dev/qa environments
- Configured NextAuth v5 environment variables (`AUTH_TRUST_HOST`)

### Documentation

- Updated `docs/guides/app_stack_proxmox.md` with:
  - Project-specific configuration examples
  - Environment file naming notes
  - Command precedence documentation

## Impact Analysis

### ✅ Backward Compatible

- **pote**: No impact (uses separate `pote` role)
- **punimTagFE/BE**: Will benefit from improved deploy script, no breaking changes
- **mirrormatch**: Uses new features, fully supported

### Project-Specific Configs (isolated)

All mirrormatch-specific settings are in `app_projects.mirrormatch` and don't affect other projects:
- `backend_migrate_cmd: "npm run db:push"` (per-environment)
- `backend_seed_cmd: "npm run db:seed"` (per-environment)
- `AUTH_TRUST_HOST: "true"` (in env_vars)

## Testing

- ✅ Mirrormatch dev environment successfully deployed
- ✅ Service starts correctly after deployment
- ✅ Environment variables loaded properly
- ✅ Database schema pushed and seeded

## Related

Fixes deployment issues encountered during mirrormatch setup:
- Non-git directory handling
- Env file preservation during clone
- Service restart permissions
- Prisma migrate vs db:push workflow

Reviewed-on: #5
2026-01-04 16:59:48 -05:00

4.9 KiB
Raw Blame History

Proxmox App Projects (LXC-first)

This guide documents the modular app-project stack that provisions Proxmox guests (dev/qa/prod) and configures a full-stack app layout on them.

What you get

  • Proxmox provisioning via API (currently LXC; VM support remains via existing roles/proxmox_vm KVM path)
  • A deployment user (appuser) with your SSH key
  • /srv/app/backend and /srv/app/frontend
  • Env file /srv/app/.env.<dev|qa|prod>
  • /usr/local/bin/deploy_app.sh to pull the right branch and restart services
  • systemd services:
    • app-backend.service
    • app-frontend.service

Where to configure projects

Edit:

  • inventories/production/group_vars/all/main.yml

Under app_projects, define projects like:

  • projectA.repo_url
  • projectA.envs.dev|qa|prod.ip/gateway/branch
  • projectA.guest_defaults (cores/memory/rootfs sizing)
  • projectA.deploy.* (install/build/migrate/start commands)
  • Optional: per-env backend_seed_cmd (e.g., npm run db:seed for dev/qa)

Adding projectB is just adding another top-level app_projects.projectB entry.

Proxmox credentials (vault)

This repo already expects Proxmox connection vars in vault (see existing Proxmox playbooks). Ensure these exist in:

  • inventories/production/group_vars/all/vault.yml (encrypted)

Common patterns:

  • vault_proxmox_host: 10.0.10.201
  • vault_proxmox_user: e.g. root@pam or ansible@pve
  • vault_proxmox_node: e.g. pve
  • Either:
    • vault_proxmox_password, or
    • vault_proxmox_token + vault_proxmox_token_id

Debian LXC template

The LXC provisioning uses lxc_ostemplate, defaulting to a Debian 12 template string like:

local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst

If your Proxmox has a different template filename, change lxc_ostemplate in inventories/production/group_vars/all/main.yml.

Running it

Provision + configure one project:

ansible-playbook -i inventories/production playbooks/app/site.yml -e app_project=projectA

Provision + configure all projects in app_projects:

ansible-playbook -i inventories/production playbooks/app/site.yml

Only provisioning (Proxmox API):

ansible-playbook -i inventories/production playbooks/app/provision_vms.yml -e app_project=projectA

Only OS/app configuration:

ansible-playbook -i inventories/production playbooks/app/configure_app.yml -e app_project=projectA

Limiting to a single env (dev/qa/prod)

  • Pass -e app_env=dev (or qa/prod) to provision/configure only that environment for the selected project.
  • Example (provision dev only): 
    ansible-playbook -i inventories/production playbooks/app/provision_vms.yml -e app_project=mirrormatch -e app_env=dev
    Configure/dev only: 
    ansible-playbook -i inventories/production playbooks/app/configure_app.yml -e app_project=mirrormatch -e app_env=dev

Example: mirrormatch project

  • Config lives in inventories/production/group_vars/all/main.yml under app_projects.mirrormatch (dev/qa/prod guests, repo URL, migrate/start commands, env vars).
  • Secrets live in the vault: vault_mirrormatch_database_url_* (and optional vault_mirrormatch_shadow_database_url_*), plus an optional repo deploy key vault_mirrormatch_git_ssh_key.
  • Run end-to-end:
make app PROJECT=mirrormatch

Run provisioning only / configure only:

make app-provision PROJECT=mirrormatch
make app-configure PROJECT=mirrormatch

Optional: SSH aliases on your workstation

To write ~/.ssh/config entries (disabled by default):

ansible-playbook -i inventories/production playbooks/app/ssh_client_config.yml -e manage_ssh_config=true -e app_project=projectA

This creates aliases like projectA-dev, projectA-qa, projectA-prod.

Project-Specific Configuration

Environment-Specific Commands

Projects can override deploy commands per environment:

envs:
  dev:
    backend_migrate_cmd: "npm run db:push"  # Override default migrate command
    backend_seed_cmd: "npm run db:seed"      # Optional: seed database

Precedence order:

  1. env_def.backend_migrate_cmd (per-environment override)
  2. project_def.deploy.backend_migrate_cmd (project default)
  3. Global default (npm run migrate)

Environment File Naming

The systemd service uses EnvironmentFile=/srv/app/.env.<env> (e.g., .env.dev). Systemd loads these variables into the service environment.

Note: Next.js has its own env file loading that looks for .env, .env.local, .env.production, etc. If your Next.js app isn't reading env vars, consider:

  • Using .env.local for dev (Next.js loads this automatically)
  • Or ensure your app reads from process.env (systemd-injected vars)

Project Types

  • Standard Node.js apps (mirrormatch, punimTagBE/FE): Use app_setup role
  • Python apps (pote): Use pote role (completely separate deployment path)

Changes to app_setup role affect all Node.js projects but are backward-compatible.