homelab/ansible/playbooks/RUN-GITVANA-BUN.md

Run Gitvana Bun Deployment

This runbook deploys Gitvana directly to Linux VM/LXC hosts using the Ansible role gitvana_bun_host.

Files added

• roles/gitvana_bun_host/*
• playbooks/deploy-gitvana-bun.yml
• group_vars/all/gitvana_bun.yml

1) Prepare control node

From the repository root:

cd ansible
ansible --version
ansible-galaxy collection install -r requirements.yml

2) Confirm target host access

Use your existing inventory and test connectivity:

ansible -i inventory/hosts.ini docker_nodes -m ping

If you want a single host, replace docker_nodes with a host like heimdall.

3) Review or override deployment variables

Default values are in group_vars/all/gitvana_bun.yml and role defaults.

Common overrides:

-e gitvana_target_hosts=heimdall
-e gitvana_repo_version=main
-e gitvana_service_port=3000
-e gitvana_run_mode=preview

4) Run deployment

Deploy to all docker_nodes:

ansible-playbook -i inventory/hosts.ini playbooks/deploy-gitvana-bun.yml

Deploy to one host:

ansible-playbook -i inventory/hosts.ini playbooks/deploy-gitvana-bun.yml -e gitvana_target_hosts=heimdall

5) Verify service

Check status on target host:

sudo systemctl status gitvana --no-pager
sudo journalctl -u gitvana -n 100 --no-pager
curl -I http://127.0.0.1:3000/

6) Day-2 operations

Redeploy after code updates:

ansible-playbook -i inventory/hosts.ini playbooks/deploy-gitvana-bun.yml -e gitvana_target_hosts=heimdall

Restart service only:

ansible -i inventory/hosts.ini heimdall -b -m ansible.builtin.systemd -a "name=gitvana state=restarted"

Troubleshooting quick checks

• Ensure Bun is present: which bun && bun --version
• Ensure app directory is owned by runtime user: ls -la /opt/gitvana
• Ensure service unit exists: cat /etc/systemd/system/gitvana.service
• Ensure selected host can access the git repository URL over network