Fix Troubleshooting page & broken links (#37)

* Add configure_caddy.md to docs

* Fix indentation in Troubleshooting; Fix links; Add abbreviations to Core (CCN) and Compute (CRN) directories for recognizability

* Clarify supervisor restart command

Author: MHHukiewitz

docs/computing/volumes/persistent.md

@@ -3,7 +3,7 @@
 Persistent volumes are logical block disks that are attached to virtual machines running programs
 in [on-demand](../on_demand.md) or [persistent](../persistent.md) execution modes. They are typically used to store
 mutable data such as databases and persist data. Currently, persistent volumes are only stored on
-the [Compute Resource Node](../../nodes/compute/index.md) (CRN) that is executing the program. Automatic backups and restoration
+the [Compute Resource Node](../../nodes/Compute_(CRN)/index.md) (CRN) that is executing the program. Automatic backups and restoration
 in case of failure of the CRN is a feature that is planned to be added in the future, and is currently left to the user.
 
 A persistent volume has the following properties:

docs/index.md

@@ -8,7 +8,7 @@ information, resources, and tools to get started with the Aleph.im project.
 - Read the [Overview](./overview.md) to understand what Aleph.im is and how it works.
 - Use our [Python](./libraries/python.md) and [Typescript](./libraries/typescript.md) SDKs.
 - Follow a [Tutorial to run Python code on aleph.im](guides/python/getting_started.md).
-- Become part of the network by managing a [Core Channel Node](nodes/core/index.md) or a [Compute Resource Node](nodes/compute/index.md).
-- Trouble setting up your node? Check out our [Troubleshooting Guide](nodes/compute/troubleshooting.md).
+- Become part of the network by managing a [Core Channel Node](nodes/Core_(CCN)/index.md) or a [Compute Resource Node](nodes/Compute_(CRN)/index.md).
+- Trouble setting up your node? Check out our [Troubleshooting Guide](nodes/Compute_(CRN)/troubleshooting.md).
 - Chat on our [Telegram group](https://t.me/alephim).
 - Engage on our [Discourse Channel](https://community.aleph.im/)

docs/nodes/compute/index.md renamed to docs/nodes/Compute_(CRN)/index.md

@@ -6,7 +6,7 @@ For production using official Debian packages.
 
 ## 1. Requirements
 
-- A [supported Linux server](../src/aleph/vm/orchestrator/README.md#1-supported-platforms)
+- A [supported Linux server](https://github.com/aleph-im/aleph-vm/tree/main/src/aleph/vm/orchestrator#1-supported-platforms)
 - A public domain name from a registrar and top level domain you trust. 
 
 In order to run an official Aleph.im Compute Resource Node (CRN), you will also need the following resources:
@@ -26,15 +26,15 @@ You will need a public domain name with access to add TXT and wildcard records.
 
 Run the following commands as `root`:
 
-First install the [VM-Connector](../vm_connector/README.md) using Docker:
+First install the [VM-Connector](https://github.com/aleph-im/aleph-vm/tree/main/vm_connector) using Docker:
 ```shell
 apt update
 apt upgrade
 apt install -y docker.io apparmor-profiles
 docker run -d -p 127.0.0.1:4021:4021/tcp --restart=always --name vm-connector alephim/vm-connector:alpha
 ```
 
-Then install the [VM-Supervisor](../src/aleph/vm/orchestrator/README.md) using the official Debian package.
+Then install the [VM-Supervisor](https://github.com/aleph-im/aleph-vm/tree/main/src/aleph/vm/orchestrator) using the official Debian package.
 The procedure is similar for updates.
 ```shell
 wget -P /opt https://github.com/aleph-im/aleph-vm/releases/download/0.3.0/aleph-vm.debian-11.deb
@@ -99,7 +99,7 @@ HTTPS/TLS certificates on time.
 
 First, create a domain name that points to the server on IPv4 (A) and IPv6 (AAAA).
 
-This is a simple configuration. For more options, check [CONFIGURE_CADDY.md](CONFIGURE_CADDY.md).
+This is a simple configuration. For more options, check [CONFIGURE_CADDY.md](configure_caddy.md).
 
 Again, run these commands as `root`:
 ```shell

docs/nodes/compute/installation/Debian-11.md renamed to docs/nodes/Compute_(CRN)/installation/Debian-11.md

@@ -6,7 +6,7 @@ For production using official Debian packages.
 
 ## 1. Requirements
 
-- A [supported Linux server](../src/aleph/vm/orchestrator/README.md#1-supported-platforms)
+- A [supported Linux server](https://github.com/aleph-im/aleph-vm/tree/main/src/aleph/vm/orchestrator#1-supported-platforms)
 - A public domain name from a registrar and top level domain you trust. 
 
 In order to run an official Aleph.im Compute Resource Node (CRN), you will also need the following resources:
@@ -26,15 +26,15 @@ You will need a public domain name with access to add TXT and wildcard records.
 
 Run the following commands as `root`:
 
-First install the [VM-Connector](../vm_connector/README.md) using Docker:
+First install the [VM-Connector](https://github.com/aleph-im/aleph-vm/tree/main/vm_connector) using Docker:
 ```shell
 apt update
 apt upgrade
 apt install -y docker.io apparmor-profiles
 docker run -d -p 127.0.0.1:4021:4021/tcp --restart=always --name vm-connector alephim/vm-connector:alpha
 ```
 
-Then install the [VM-Supervisor](../src/aleph/vm/orchestrator/README.md) using the official Debian package.
+Then install the [VM-Supervisor](https://github.com/aleph-im/aleph-vm/tree/main/src/aleph/vm/orchestrator) using the official Debian package.
 The procedure is similar for updates.
 ```shell
 wget -P /opt https://github.com/aleph-im/aleph-vm/releases/download/0.3.0/aleph-vm.debian-12.deb
@@ -100,7 +100,7 @@ HTTPS/TLS certificates on time.
 
 First, create a domain name that points to the server on IPv4 (A) and IPv6 (AAAA).
 
-This is a simple configuration. For more options, check [CONFIGURE_CADDY.md](CONFIGURE_CADDY.md).
+This is a simple configuration. For more options, check [CONFIGURE_CADDY.md](configure_caddy.md).
 
 Again, run these commands as `root`:
 ```shell

docs/nodes/compute/installation/Debian-12.md renamed to docs/nodes/Compute_(CRN)/installation/Debian-12.md

@@ -6,7 +6,7 @@ For production using official Debian packages.
 
 ## 1. Requirements
 
-- A [supported Linux server](../src/aleph/vm/orchestrator/README.md#1-supported-platforms)
+- A [supported Linux server](https://github.com/aleph-im/aleph-vm/tree/main/src/aleph/vm/orchestrator#1-supported-platforms)
 - A public domain name from a registrar and top level domain you trust. 
 
 In order to run an official Aleph.im Compute Resource Node (CRN), you will also need the following resources:
@@ -26,15 +26,15 @@ You will need a public domain name with access to add TXT and wildcard records.
 
 Run the following commands:
 
-First install the [VM-Connector](../vm_connector/README.md) using Docker:
+First install the [VM-Connector](https://github.com/aleph-im/aleph-vm/tree/main/vm_connector) using Docker:
 ```shell
 sudo apt update
 sudo apt upgrade
 sudo apt install -y docker.io
 docker run -d -p 127.0.0.1:4021:4021/tcp --restart=always --name vm-connector alephim/vm-connector:alpha
 ```
 
-Then install the [VM-Supervisor](../src/aleph/vm/orchestrator/README.md) using the official Debian package.
+Then install the [VM-Supervisor](https://github.com/aleph-im/aleph-vm/tree/main/src/aleph/vm/orchestrator) using the official Debian package.
 The procedure is similar for updates.
 ```shell
 sudo wget -P /opt https://github.com/aleph-im/aleph-vm/releases/download/0.3.0/aleph-vm.ubuntu-22.04.deb
@@ -101,7 +101,7 @@ HTTPS/TLS certificates on time.
 
 First, create a domain name that points to the server on IPv4 (A) and IPv6 (AAAA).
 
-This is a simple configuration. For more options, check [CONFIGURE_CADDY.md](CONFIGURE_CADDY.md).
+This is a simple configuration. For more options, check [CONFIGURE_CADDY.md](configure_caddy.md).
 
 Again, run these commands as `root`:
 ```shell

docs/nodes/compute/installation/Ubuntu-20.04.md renamed to docs/nodes/Compute_(CRN)/installation/Ubuntu-20.04.md

@@ -0,0 +1,120 @@
+# Caddy Reverse-proxy for Aleph-VM
+
+A reverse-proxy is required for production use. It allows:
+
+ - A different domain name for each VM function
+ - Secure connections using HTTPS
+ - Load balancing between multiple servers
+
+Using a different domain name for each VM function is important when running web applications, 
+both for security and usability purposes. 
+
+The VM Supervisor supports using domains in the form `https://identifer.vm.yourdomain.org`, where
+_identifier_ is the identifier/hash of the message describing the VM function and `yourdomain.org` 
+represents your domain name.
+
+## 1. Wildcard certificates
+
+A wildcard certificate is recommended to allow any subdomain of your domain to work.
+
+You can create one using [Let's Encrypt](https://letsencrypt.org/) and
+[Certbot](https://certbot.eff.org/) with the following instructions.
+
+```shell
+sudo apt install -y certbot
+
+certbot certonly --manual --email [email protected] --preferred-challenges dns \
+  --server https://acme-v02.api.letsencrypt.org/directory --agree-tos \
+  -d 'vm.yourdomain.org,*.vm.yourdomain.org'
+```
+
+## 2. Caddy Server
+
+In this documentation, we will install the modern [Caddy](https://caddyserver.com/) reverse-proxy.
+
+Replace `vm.yourdomain.org` with your domain of choice. 
+
+To install on Debian/Ubuntu, according to the
+[official instructions](https://caddyserver.com/docs/install#debian-ubuntu-raspbian):
+```shell
+sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
+sudo apt update
+sudo apt install caddy
+```
+
+Then give Caddy access to the certificates generated by Certbot:
+```shell
+chmod 750 /etc/letsencrypt/live/
+chmod 750 /etc/letsencrypt/archive/
+chmod 640 /etc/letsencrypt/archive/vm.yourdomain.org/privkey1.pem
+chgrp -R caddy /etc/letsencrypt/archive/
+chgrp -R caddy /etc/letsencrypt/live/
+```
+
+Configure Caddy:
+```shell
+cat >/etc/caddy/Caddyfile <<EOL
+
+vm.yourdomain.org:443 {
+    tls /etc/letsencrypt/live/vm.yourdomain.org/fullchain.pem /etc/letsencrypt/live/vm.yourdomain.org/privkey.pem
+    reverse_proxy http://127.0.0.1:4020 {
+        # Forward Host header to the backend
+        header_up Host {host}
+    }
+}
+
+*.vm.yourdomain.org:443 {
+    tls /etc/letsencrypt/live/vm.yourdomain.org/fullchain.pem /etc/letsencrypt/live/vm.yourdomain.org/privkey.pem
+    reverse_proxy http://127.0.0.1:4020 {
+        # Forward Host header to the backend
+        header_up Host {host}
+    }
+}
+EOL
+```
+
+Optionally, you can allow users to host their website using their own domains using the following
+configuration. Be careful about rate limits if you enable `on_demand` TLS, 
+see the [Caddy documentation on On-Demand TLS](https://caddyserver.com/docs/automatic-https#on-demand-tls).
+```shell
+cat >/etc/caddy/Caddyfile <<EOL
+{
+    on_demand_tls {
+        interval 60s
+        burst    5
+    }
+}
+
+
+vm.yourdomain.org:443 {
+    tls /etc/letsencrypt/live/vm.yourdomain.org/fullchain.pem /etc/letsencrypt/live/vm.yourdomain.org/privkey.pem
+    reverse_proxy http://127.0.0.1:4020 {
+        header_up Host {host}
+    }
+}
+
+*.vm.yourdomain.org:443 {
+    tls /etc/letsencrypt/live/vm.yourdomain.org/fullchain.pem /etc/letsencrypt/live/vm.yourdomain.org/privkey.pem
+    reverse_proxy http://127.0.0.1:4020 {
+        # Forward Host header to the backend
+        header_up Host {host}
+    }
+}
+
+*:443 {
+    tls {
+        on_demand
+    }
+    reverse_proxy http://127.0.0.1:4020 {
+        # Forward Host header to the backend
+        header_up Host {host}
+    }
+}
+EOL
+```
+
+Finally, restard Caddy:
+```shell
+sudo systemctl restart caddy

docs/nodes/compute/installation/Ubuntu-22.04.md renamed to docs/nodes/Compute_(CRN)/installation/Ubuntu-22.04.md

@@ -16,17 +16,25 @@ After setting up a CRN, users may encounter a `404: Invalid message reference` e
 - The hostname might not be correctly configured in the aleph-vm settings.
 
 ### Troubleshooting Steps
+
 1. **Recheck SSL Configuration:**
-   - Confirm that SSL certificates are correctly installed and configured.
-   - Review the SSL configuration in the web server (e.g., Caddy, Nginx) to ensure it's correctly pointing to the intended ports with the right certificate paths.
+    - Confirm that SSL certificates are correctly installed and configured.
+    - Review the SSL configuration in the web server (e.g., Caddy, Nginx) to ensure it's correctly pointing to the intended ports with the right certificate paths.
+
 2. **Configure Hostname Correctly:**
-   - Ensure the hostname is properly configured as per the [CRN installation guide](./installation/Debian-11.md#2-installation).
-   - Make sure the domain name in the supervisor.env file matches the domain used in your SSL configuration.
+
+    - Ensure the hostname is properly configured as per the [CRN installation guide](./installation/Debian-11.md#2-installation).
+    - Make sure the domain name in the supervisor.env file matches the domain used in your SSL configuration.
+
 3. **Restart Services:**
-   - After updating the hostname, restart the relevant services to apply the changes.
-   - This may include restarting the Docker container and the web server service.
+
+    - After updating the hostname, restart the relevant services to apply the changes.
+    - This may include restarting the Docker container and the web server service.
+
 4. **Review Log Files:**
-   - If the problem still persists, check the log files of both the Docker container and the web server for any specific error messages related to SSL or hostname configurations.
+
+    - If the problem still persists, check the log files of both the Docker container and the web server for any specific error messages related to SSL or hostname configurations.
+
 
 ## 2) SQUASHFS Errors in Diagnostic VM
 ### Issue Summary
@@ -47,13 +55,22 @@ The runtime of the new diagnostic VM appears to be improperly downloaded or corr
 ### Troubleshooting Steps
 
 1. **Clear Cache**: Remove the cache of the problematic file using the diagnostic VM hash. This can be done by deleting the file located at `/var/cache/aleph/runtime/$RUNTIME_HASH`.
-   - Navigate to the cache directory: `cd /var/cache/aleph/runtime/`.
-   - Locate the file with the corresponding `$RUNTIME_HASH`.
-   - Remove the file: `sudo rm -f $RUNTIME_HASH`.
+
+    - Navigate to the cache directory: `cd /var/cache/aleph/vm/runtime/`.
+    - Locate the file with the corresponding `$RUNTIME_HASH`.
+    - Remove the file:
+   ```shell
+   sudo rm -f $RUNTIME_HASH
+   ```
+
 2. **Restart Supervisor**: After deleting the problematic file, restart the supervisor system. This should trigger the re-download of the runtime file.
-   - Restart the supervisor: `sudo systemctl restart supervisor` (or the equivalent command for your system).
+
+    - Restart the supervisor: `sudo systemctl restart supervisor` (or `aleph-vm-supervisor.service` when installing from source).
+
 3. **Re-download**: Upon restart, the system will automatically attempt to re-download the runtime, replacing the corrupted file.
-   - If the problem persists, further investigation into network stability or hardware integrity may be necessary.
+
+    - If the problem persists, further investigation into network stability or hardware integrity may be necessary.
+
 
 ## 3) Missing Diagnostic VM Metrics
 ### Issue Summary
@@ -79,25 +96,30 @@ Check that both work on your node, on an URL similar to
 ### Troubleshooting Steps
 
 1. **Upgrade Node Software:**
+
     - Ensure the node is running the latest CRN version.
 
 2. **Disable IPv6 Forwarding:**
+
     - If upgrading does not resolve the issue, try disabling IPv6 forwarding:
         - Set `ALEPH_VM_IPV6_FORWARDING_ENABLED=False` in `/etc/aleph-vm/supervisor.env`.
         - Manually check if IPv6 forwarding is still active:
             ```shell
             cat /proc/sys/net/ipv6/conf/all/forwarding
             ```
-            If the output is 1, disable it with:
+          If the output is 1, disable it with:
             ```shell
             echo 0 > /proc/sys/net/ipv6/conf/all/forwarding
             ```
 
 3. **Clear Cache:**
-    See [SQUASHFS Errors in running diagnostic VM](#squashfs-errors-in-running-diagnostic-vm). 
+
+    - See [SQUASHFS Errors in running diagnostic VM](#squashfs-errors-in-running-diagnostic-vm).
+
 4. **Contact Cloud Provider:**
+
     - If the issue persists, ask your Cloud Provider:
-      - "I tried to enable IPv6 forwarding on my server. This makes my machine unreachable over IPv6. Why is that?"
+      "I tried to enable IPv6 forwarding on my server. This makes my machine unreachable over IPv6. Why is that?"
 
 
 ## 4) IPv6 Unreachable
@@ -117,9 +139,11 @@ When using IPv6 on a node, the network is unreachable.
 
 ### Troubleshooting Steps
 1. **Check IPv6 Configuration:**
+
     - Ensure that IPv6 is enabled on the network interface.
     - Verify that the IPv6 address is correctly assigned to the interface.
     - Confirm that the gateway for IPv6 is set up correctly.
+
 2. **Review Netplan Configuration (for Ubuntu systems):**
 
     - Open the Netplan configuration file located typically at /etc/netplan/*.yaml.
@@ -138,9 +162,13 @@ When using IPv6 on a node, the network is unreachable.
           nameservers:
             addresses: ["2001:4860:4860::8888", "2001:4860:4860::8844"]
     ```
-    After making changes, apply them with `sudo netplan apply`.
-3. **Check Network Interface:** 
+   After making changes, apply them with `sudo netplan apply`.
+
+3. **Check Network Interface:**
+
     - Use `ip -6 addr show` to check if the IPv6 address is assigned to the network interface.
     - Use `ip -6 route show` to verify the default route for IPv6.
+
 4. **Test Network Connectivity:**
+
     - Use `ping6` to ping the local IPv6 gateway or known IPv6 addresses like Google's DNS `2001:4860:4860::8888` to test connectivity.

docs/nodes/Compute_(CRN)/installation/configure_caddy.md

@@ -4,7 +4,7 @@ Node operators and stakers receive rewards for contributing to the aleph.im netw
 
 ## Core Channel Nodes
 
-A [Core Channel Node](../core/index.md) (CCN) is active when it is registered on the [aleph.im account page](
+A [Core Channel Node](../Core_(CCN)/index.md) (CCN) is active when it is registered on the [aleph.im account page](
 https://account.aleph.im), has enough ALEPH token staked on it and has a [score](scores.md) non null.
 
 The performance score of a CCN affects the rewards distributed to the operator and stakers of the node the following way:
@@ -14,7 +14,7 @@ The performance score of a CCN affects the rewards distributed to the operator a
 - The complete reward is distributed when the score is equal to or greater than 80%
 
 The second factor that affects the rewards of a CCN is its linking to
-[Compute Resource Nodes](../compute/index.md) (CRN).  A CCN can have up to 3 CRNs linked to it, and a the CCN
+[Compute Resource Nodes](../Compute_(CRN)/index.md) (CRN).  A CCN can have up to 3 CRNs linked to it, and a the CCN
 will incur a penalty of 10% of the rewards for each spot unfilled or filled with a defaulting CRN (score of 0).
 
 The rewards distributed does not depend on the score of other nodes in the network. Less token from the pool