ilia
0a937fd1b4
All checks were successful
CI / skip-ci-check (push) Successful in 1m23s
CI / lint-and-test (push) Successful in 1m27s
CI / ansible-validation (push) Successful in 2m59s
CI / secret-scanning (push) Successful in 1m24s
CI / dependency-scan (push) Successful in 1m29s
CI / sast-scan (push) Successful in 2m41s
CI / license-check (push) Successful in 1m27s
CI / vault-check (push) Successful in 2m29s
CI / playbook-test (push) Successful in 2m38s
CI / container-scan (push) Successful in 1m56s
CI / sonar-analysis (push) Successful in 2m33s
CI / workflow-summary (push) Successful in 1m21s
## 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
153 lines
4.9 KiB
Markdown
153 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
ansible-playbook -i inventories/production playbooks/app/site.yml -e app_project=projectA
|
|
```
|
|
|
|
Provision + configure all projects in `app_projects`:
|
|
|
|
```bash
|
|
ansible-playbook -i inventories/production playbooks/app/site.yml
|
|
```
|
|
|
|
Only provisioning (Proxmox API):
|
|
|
|
```bash
|
|
ansible-playbook -i inventories/production playbooks/app/provision_vms.yml -e app_project=projectA
|
|
```
|
|
|
|
Only OS/app configuration:
|
|
|
|
```bash
|
|
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):
|
|
```bash
|
|
ansible-playbook -i inventories/production playbooks/app/provision_vms.yml -e app_project=mirrormatch -e app_env=dev
|
|
```
|
|
Configure/dev only:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make app PROJECT=mirrormatch
|
|
```
|
|
|
|
Run provisioning only / configure only:
|
|
|
|
```bash
|
|
make app-provision PROJECT=mirrormatch
|
|
make app-configure PROJECT=mirrormatch
|
|
```
|
|
|
|
## Optional: SSH aliases on your workstation
|
|
|
|
To write `~/.ssh/config` entries (disabled by default):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
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.
|
|
|
|
|