Review of deployment/development guides

Vagrantfile

@@ -1,3 +1,7 @@
+if ARGV.any? { |arg| %w[up provision reload].include?(arg) } && ENV['ANSIBLE_COLLECTIONS_PATH'].nil?
+  abort("Do not use vagrant directly, use: ./forge vms start\n")
+end
+
 DOMAIN = ENV.fetch('VAGRANT_DOMAIN', 'example.com'.freeze)
 
 # Official CentOS libvirt images include swap; Vagrant Cloud boxes do not.

docs/developer/deployment.md

@@ -30,7 +30,7 @@ Deploys a Foreman server. This is the primary deployment type and the default en
 
 Deploys a Foreman Proxy node that connects to a Foreman server.
 
-Before running the proxy deployment, an auth bundle must be generated on the Foreman server and copied to the proxy VM:
+Before running the proxy deployment, an auth bundle must be generated on the Foreman server and copied to the control node:
 
 1. On the **Foreman server**, generate an auth bundle for the proxy hostname:
 
@@ -43,18 +43,18 @@ Before running the proxy deployment, an auth bundle must be generated on the For
 > [!NOTE]
 > The bundle includes the proxy's certificates and OAuth credentials needed for the proxy to communicate with the Foreman server.
 
-2. Copy the bundle to the **proxy VM**:
+2. Copy the bundle to the **control node**:
 
-   ```console
-   # scp /var/lib/foremanctl/certs/bundles/proxy.example.com.tar.gz root@proxy.example.com:/root/proxy.example.com.tar.gz
+   ```bash
+   vagrant ssh quadlet -- sudo cat /var/lib/foremanctl/certs/bundles/proxy.example.com.tar.gz > proxy.example.com.tar.gz
    ```
 
-3. On the **proxy VM**, run the deployment:
+3. On the **control node** (where foremanctl is installed), run the deployment remotely via SSH:
 
    ```console
-   # foremanctl deploy-proxy \
+   # foremanctl deploy-proxy proxy.example.com \
      --flavor foreman-proxy-content \
-     --auth-bundle /root/proxy.example.com.tar.gz \
+     --auth-bundle $(pwd)/proxy.example.com.tar.gz \
      --foreman-fqdn quadlet.example.com
    ```
 

docs/developer/development-environment.md

@@ -28,14 +28,17 @@ The development environment provides:
    ```
 
 2. **Access the environment:**
-   - SSH into the VM: `vagrant ssh`
+   - To run commands on the VM, SSH into it: `vagrant ssh quadlet`
    - Navigate to Foreman directory: `cd /home/vagrant/foreman`
    - Start Rails server: `bundle exec foreman start`
 
 3. **Access URLs:**
    - Foreman UI: `http://$(hostname -f):3000` (development server)
    - Production-style UI: `https://$(hostname -f)` (via Apache proxy)
 
+> [!NOTE]
+> Do not run `./foremanctl` or `./forge` from inside the VM. These commands should be run on the **control node** (where foremanctl source is cloned) and use the `--target-host` parameter to deploy to the VM remotely via SSH. See [Deploying to a Remote Host](#deploying-to-a-remote-host) for details.
+
 ### Deploying to a Remote Host
 
 You can deploy directly to a remote host using the `--target-host` parameter:
@@ -67,6 +70,26 @@ katello-production:
   disk_size: 50
 ```
 
+### DNS
+
+This repository does not use the `vagrant-hostmanager` plugin; instead, it automatically configures `/etc/hosts` inside all VMs during provisioning. However, to enable host-to-VM communication (e.g., using `ssh` or `scp` from your host, which is required for proxy/capsule node deployments), you need a working DNS resolution of the libvirt VMs.
+
+This can be configured by editing the default libvirt network on your host:
+
+```bash
+virsh net-edit default
+```
+
+And ensuring that the domain name tag matches your `VAGRANT_DOMAIN` environment variable (which defaults to `example.com`):
+
+```xml
+<network>
+  <domain name='example.com'/>
+</network>
+```
+
+Once VMs are running, the guest hostnames should resolve automatically on modern Linux distributions (tested on Fedora).
+
 ### SSH Authentication
 
 When deploying to remote hosts that require SSH password authentication:

src/playbooks/deploy-proxy/deploy-proxy.yaml

@@ -1,7 +1,7 @@
 ---
 - name: Setup proxy machine
   hosts:
-    - proxy
+    - "{{ target_host }}"
   become: true
   vars:
     flavor: foreman-proxy-content

src/playbooks/deploy-proxy/metadata.obsah.yaml

@@ -7,6 +7,9 @@ variables:
     help: Base flavor to use in this deployment.
     choices:
       - foreman-proxy-content
+  target_host:
+    help: Target hostname or IP address for the proxy deployment
+    action: store
   auth_bundle:
     help: Path to the auth bundle tar file.
     type: AbsolutePath