ops/deployments-from-scratch.md

@@ -39,7 +39,7 @@
 
 * Target dir: `/srv/op-sepolia/optimism-deployment`
 
-* Cleanup an existing deployment if required:
+* Cleanup an existing deployment on virtual machine if required:
 
   ```bash
   cd /srv/op-sepolia
@@ -99,16 +99,51 @@
 
 ### Run
 
-* Setup and run L2 by executing the `run-optimism.yml` Ansible playbook:
+* Execute the `run-optimism.yml` Ansible playbook on the remote host to set up and run L2:
 
-  ```bash
-  LANG=en_US.utf8 ansible-playbook -i localhost, --connection=local run-optimism.yml --extra-vars='{ "target_host": "localhost"}' --user $USER
-  ```
+  * Create a new `hosts.ini` file:
 
-  * For skipping container build, run with `"skip_container_build" : true`:
+      ```bash
+      cp ../hosts.example.ini hosts.ini
+      ```
+
+  * Edit the [`hosts.ini`](./hosts.ini) file to run the playbook on a remote machine:
+
+    ```ini
+    [<deployment_host>]
+    <host_name> ansible_host=<target_ip> ansible_user=<ssh_user> ansible_ssh_common_args='-o ForwardAgent=yes'
+    ```
+
+    - Replace `<deployment_host>` with `l2_host`
+    - Replace `<host_name>` with the alias of your choice
+    - Replace `<target_ip>` with the IP address or hostname of the target machine
+    - Replace `<ssh_user>` with the SSH username (e.g., dev, ubuntu)
+
+  * Verify that you are able to connect to the host using the following command
 
     ```bash
-    LANG=en_US.utf8 ansible-playbook -i localhost, --connection=local run-optimism.yml --extra-vars='{"target_host" : "localhost", "skip_container_build": true}' -kK --user $USER
+    ansible all -m ping -i hosts.ini -k
+
+    # Expected output:
+    # <host_name> | SUCCESS => {
+    #  "ansible_facts": {
+    #      "discovered_interpreter_python": "/usr/bin/python3.10"
+    #  },
+    #  "changed": false,
+    #  "ping": "pong"
+    # }
+    ```
+
+  * Execute the `run-optimism.yml` Ansible playbook for remote deployment:
+
+    ```bash
+    LANG=en_US.utf8 ansible-playbook -i hosts.ini run-optimism.yml --extra-vars='{ "target_host": "l2_host"}'  --user $USER -kK
+    ```
+
+  * For skipping container build, run with `"skip_container_build" : true` in the `--extra-vars` parameter:
+
+    ```bash
+    LANG=en_US.utf8 ansible-playbook -i hosts.ini run-optimism.yml --extra-vars='{ "target_host": "l2_host", "skip_container_build": true }' --user $USER -kK
     ```
 
 * Bridge funds on L2:
@@ -116,6 +151,7 @@
   * Set the following variables:
 
     ```bash
+    # Switch to `/srv/op-sepolia` directory on the virtual machine
     cd /srv/op-sepolia
 
     L1_RPC=http://host.docker.internal:8545