ops/deployments-from-scratch.md

@@ -163,9 +163,9 @@
 </details>
 
 <details open>
-  <summary>L1 nitro contracts deployment</summary>
+  <summary>L1 Nitro Contracts Deployment</summary>
 
-## L1 nitro contracts deployment
+## L1 Nitro Contracts Deployment
 
 * Stack: <https://git.vdb.to/cerc-io/nitro-stack>
 
@@ -173,7 +173,7 @@
 
 * Target dir: `/srv/bridge/nitro-contracts-deployment`
 
-* Cleanup an existing deployment if required:
+* Cleanup an existing deployment on virtual machine if required:
 
   ```bash
   cd /srv/bridge
@@ -186,7 +186,7 @@
 
 ### Setup
 
-* Following commands have to be executed in `testnet-ops/nitro-contracts-setup` directory
+* Following commands have to be executed in `testnet-ops/nitro-contracts-setup` directory on your local machine
 
   ```bash
   cd testnet-ops/nitro-contracts-setup
@@ -211,9 +211,9 @@
   geth_deployer_pk: ""
 
   # Custom L1 token to be deployed
-  token_name: "<token-name>"
+  token_name: ""
-  token_symbol: "<token-symbol>"
+  token_symbol: ""
-  intial_token_supply: "<token-supply>"
+  intial_token_supply: ""
   ```
 
 * Update the target dir in `setup-vars.yml`:
@@ -226,19 +226,54 @@
 
 ### Run
 
-* To deploy nitro contracts locally, execute the `deploy-contracts.yml` Ansible playbook:
+* Execute the `deploy-contracts.yml` Ansible playbook on the remote host to deploy Nitro contracts:
+
+  * Create a new `hosts.ini` file:
 
     ```bash
-  LANG=en_US.utf8 ansible-playbook deploy-contracts.yml --extra-vars='{ "target_host": "localhost"}' --user $USER -kK
+    cp ../hosts.example.ini hosts.ini
     ```
 
-  * For skipping container build, set `"skip_container_build" : true` in the `--extra-vars` parameter:
+  * 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 `nitro_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 deploy-contracts.yml --extra-vars='{"target_host" : "localhost", "skip_container_build": true}' --user $USER -kK
+    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"
+    # }
     ```
 
-* Check logs for deployments:
+  * Execute the `deploy-contracts.yml` Ansible playbook for remote deployment:
+
+    ```bash
+    LANG=en_US.utf8 ansible-playbook -i hosts.ini deploy-contracts.yml --extra-vars='{ "target_host": "nitro_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 deploy-contracts.yml --extra-vars='{ "target_host": "nitro_host", "skip_container_build": true }' --user $USER -kK
+    ```
+
+* Check logs for deployments on the virtual machine:
 
   ```bash
   cd /srv/bridge
@@ -260,7 +295,7 @@
 
 * Target dir: `/srv/bridge/bridge-deployment`
 
-* Cleanup an existing deployment if required:
+* Cleanup an existing deployment on virtual machine if required:
 
   ```bash
   cd /srv/bridge
@@ -274,7 +309,7 @@
 
 ### Setup
 
-* Following commands have to be executed in `testnet-ops/nitro-bridge-setup` directory
+* Following commands have to be executed in `testnet-ops/nitro-bridge-setup` directory on your local machine
 
   ```bash
   cd testnet-ops/nitro-bridge-setup
@@ -329,19 +364,54 @@
 
 ### Run
 
-* Setup and run L2 by executing the `run-nitro-bridge.yml` Ansible playbook:
+* Execute the `run-nitro-bridge.yml` Ansible playbook on the remote host to deploy the L2 contracts and start the bridge:
+
+  * Create a new `hosts.ini` file:
 
       ```bash
-  LANG=en_US.utf8 ansible-playbook -i localhost, --connection=local run-nitro-bridge.yml --extra-vars='{ "target_host": "localhost"}' --user $USER
+      cp ../hosts.example.ini hosts.ini
       ```
 
-  * For skipping container build, run with `"skip_container_build" : true`:
+  * 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 `nitro_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-nitro-bridge.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"
+    # }
     ```
 
-* Check status:
+  * Execute the `run-nitro-bridge.yml` Ansible playbook for remote deployment:
+
+    ```bash
+    LANG=en_US.utf8 ansible-playbook -i hosts.ini run-nitro-bridge.yml --extra-vars='{ "target_host": "nitro_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-nitro-bridge.yml --extra-vars='{ "target_host": "nitro_host", "skip_container_build": true }' --user $USER -kK
+    ```
+
+* Check logs for deployments on the virtual machine:
 
   ```bash
   cd /srv/bridge