docs: Refactor whole "Docker Install" page

docs/install/docker/README.md

@@ -12,34 +12,88 @@ meta:
       - nodered
 ---
 
-# Docker Install
-
-This version of the FlowFuse platform is intended for running in the Docker Container management system. Typically suited for small/medium on premise deployments.
+<script>     
+   class ChecklistItem extends HTMLElement {
+
+      static observedAttributes = ["type", "task"];
+
+      constructor() {
+         super();   
+         this.type = 'required'
+         this.task = ''
+      }
+
+      attributeChangedCallback(name, oldValue, newValue) {
+        if (name === "type") {
+            this.type = newValue;
+        } else if (name === "task") {
+            this.task = newValue;
+        }
+      }
+
+      connectedCallback () {
+        const iconRequired = `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" /></svg>`
+        const iconRecommended = `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12c0 1.268-.63 2.39-1.593 3.068a3.745 3.745 0 0 1-1.043 3.296 3.745 3.745 0 0 1-3.296 1.043A3.745 3.745 0 0 1 12 21c-1.268 0-2.39-.63-3.068-1.593a3.746 3.746 0 0 1-3.296-1.043 3.745 3.745 0 0 1-1.043-3.296A3.745 3.745 0 0 1 3 12c0-1.268.63-2.39 1.593-3.068a3.745 3.745 0 0 1 1.043-3.296 3.746 3.746 0 0 1 3.296-1.043A3.746 3.746 0 0 1 12 3c1.268 0 2.39.63 3.068 1.593a3.746 3.746 0 0 1 3.296 1.043 3.746 3.746 0 0 1 1.043 3.296A3.745 3.745 0 0 1 21 12Z" /></svg>`
+        const iconOptional = `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M8.625 12a.375.375 0 1 1-.75 0 .375.375 0 0 1 .75 0Zm0 0H8.25m4.125 0a.375.375 0 1 1-.75 0 .375.375 0 0 1 .75 0Zm0 0H12m4.125 0a.375.375 0 1 1-.75 0 .375.375 0 0 1 .75 0Zm0 0h-.375M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" /></svg>`
+
+        let icon = iconRequired
+        let tooltip = "Required for Operation"
+        if (this.type === 'recommended') {
+          icon = iconRecommended
+          tooltip = "Recommended for Production"
+        } else if (this.type === 'optional') {
+          icon = iconOptional
+          tooltip = "Optional"
+        }
+        this.innerHTML = `<div class="checklist-item checklist-item--${this.type}"><span class="tooltip" data-tooltip="${tooltip}"><span class="checklist-item-status">${icon}</span><span>${this.task}</span></span></div>`
+      }
+   }
+
+   customElements.define('checklist-item', ChecklistItem);
+</script>
 
-## Prerequisites
+# Docker Install
 
-### Platform
+This guide walks you through detailed set up of FlowFuse Platform on a Docker container envoronment using Docker Compose. Typically suited for small/medium on premise deployments.
+By the end, you will have a fully functioning FlowFuse instance running in a Docker container.
 
-The following instructions assume you are running Docker on a Linux or MacOS host system.
+For a FlowFuse platform evaluation purposes, check out our [Quick Start Guide](../../quick-start/README.md).
 
-#### Digital Ocean
+The following guide walks through a full production-ready deployment. If you want to install FlowFuse for evaluation purposes, please refer to the [Quick Start Guide](../../quick-start/README.md).
 
-If you are using the Digital Ocean Docker Droplet to host FlowFuse you will need to ensure that port 80 & 443 are opened in the UFW firewall before starting.
+## Checklist
 
-```bash
-sudo ufw apply http
-sudo ufw apply https
-```
+<div class="grid grid-cols-2 gap-8">
+  <div class="checklist">
+    <label>Prerequisites</label>
+    <div>
+      <checklist-item task="Domain Name"></checklist-item>
+      <checklist-item task="Docker Engine & Docker Compose"></checklist-item>
+      <checklist-item type="recommended" task="Setup Dedicated Database"></checklist-item>
+      <checklist-item type="recommended" task="Prepare TLS Certificates"></checklist-item>
+    </div>
+  </div>
 
-We have a 1-Click Digital Ocean Droplet that will install and configure FlowFuse for you. Details can be found [here](./digital-ocean.md)
+  <div class="checklist">
+    <label>Installation</label>
+    <div>
+      <checklist-item task="Download FlowFuse"></checklist-item>
+      <checklist-item task="Configure FlowFuse"></checklist-item>
+      <checklist-item type="recommended" task="Enable HTTPS"></checklist-item>
+    </div>
+  </div>
+</div>
 
-### Docker Compose
+## Prerequisites
 
-FlowFuse uses Docker Compose to install and manage the required components. Instructions on how to install Docker Compose on your system can be found here:
+Before you begin, ensure you have the following:
 
-[https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/)
+1. **Domain Name & DNS:** A domain name that you own and can configure DNS settings for (explained in [DNS](#dns))
+2. **Install Docker:** [Docker Engine](https://docs.docker.com/engine/) and [Docker Compose](https://docs.docker.com/compose/install/) must be installed on your system (either as a standalone binary or as docker plugin)
 
-FlowFuse requires docker-compose v2
+For a production-ready environment, we also recommend: 
+* **Database:** Prepare dedicated database on a external database server (see [FAQ](#how-to-use-external-database-server%3F) for more details)
+* **TLS Certification:** Prepare TLS certificate for your domain and configure FlowFuse platform to use it (see [Enable HTTPS](#enable-https-optional))
 
 ### DNS
 
@@ -49,7 +103,7 @@ To make this work you will need to configure a DNS server to map a [wildcard dom
 
 The FlowFuse Application will be hosted on `http://forge.example.com`
 
-**Note** When testing locally you can add entries for each Node-RED instance to your `/etc/hosts` file but you must use the external IP address of the host machine, not the loopback address (`127.0.0.1`).
+**Note** At this moment FlowFuse platform is not capable to run on localhost. You must point your domain to the external IP address of the host machine, not the loopback address (`127.0.0.1`).
 
 Notes on how to setup DNS can be found [here](../dns-setup.md).
 
@@ -89,13 +143,13 @@ Otherwise you will need to contact a SSL Certificate vendor and configure Nginx
 
 **Note: Automatic TLS generation is possible only for the publicly available servers**
 
-Download additional Docker Compose file:
+In the `.env` file, set the `TLS_ENABLED` variable to `true`:
 
 ```bash
-curl -o docker-compose-tls.override.yml https://raw.githubusercontent.com/FlowFuse/docker-compose/refs/heads/main/docker-compose-tls.override.yml
+TLS_ENABLED=true
 ```
 
-Proceed to the [next paragraph](#start-flowfuse-platform) to start the platform.
+Proceed to the [next paragraph](#start-flowfuse-platform) to start the platform with automatically generated TLS certificate.
 
 #### Custom TLS Certificate
 
@@ -105,11 +159,12 @@ To configure FlowFuse platform with your certificate, you need to have:
 * certificate key file
 * certificate's full chain (server certificate and intermediate certificates bundled into single file)
 
-To add your certificate to the platform, edit the `.env` file downloaded earlier and set values for `TLS_CERTIFICATE` and `TLS_KEY` variables. `TLS_CERTIFICATE` should contain the full chain of the certificate while `TLS_KEY` should contain the key file.
-Example of `.env` file with TLS certificate configuration:
+To add your certificate to the platform, edit the `.env` file downloaded earlier and set values for `TLS_ENABLED`, `TLS_CERTIFICATE` and `TLS_KEY` variables. `TLS_ENABLED` variable should be set to `true`.
+`TLS_CERTIFICATE` should contain the full chain of the certificate while `TLS_KEY` should contain the key file.
+Example of `.env` file with the custom TLS certificate configuration:
 
 ```bash
-DOMAIN=example
+TLS_ENABLED=true
 TLS_CERTIFICATE="
 -----BEGIN CERTIFICATE-----
 MIIFfzCCBKegAwIBAgISA0
@@ -128,12 +183,6 @@ MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQD
 "
 ```
 
-Lastly, download the `docker-compose-tls.override.yml` file:
-
-```bash
-curl -o docker-compose-tls.override.yml https://raw.githubusercontent.com/FlowFuse/docker-compose/refs/heads/main/docker-compose-tls.override.yml
-```
-
 ## Start FlowFuse platform
 
 **Note: Make sure all configuration are done above before proceeding.**
@@ -143,20 +192,22 @@ curl -o docker-compose-tls.override.yml https://raw.githubusercontent.com/FlowFu
 #### With automatic TLS certificate generation
 
 ```bash
-docker compose -f docker-compose.yml -f docker-compose-tls.override.yml --profile autossl -p flowfuse up -d
+docker compose --profile autotls -p flowfuse up -d
 ```
-#### With custom TLS certificate
+
+#### In all other scenarios, including custom TLS certificate
 
 ```bash
-docker compose -f docker-compose.yml -f docker-compose-tls.override.yml -p flowfuse up -d
+docker compose -p flowfuse up -d
 ```
 
-#### In all other cases
+The platform will take a few minutes to start up. You can check the status of the containers by running:
 
 ```bash
-docker compose -p flowfuse up -d
+docker compose -p flowfuse ps
 ```
 
+
 Visit `forge.example.com` (replace `example.com` with the domain configured in the `.env` file) in your browser to access the FlowFuse platform.
 
 
@@ -169,34 +220,10 @@ For more information, follow [this guide](../first-run.md).
 
 Once you have finished setting up the admin user there are some Docker specific items to consider.
 
-
-### Using FlowFuse File Storage
-
-Node-RED instances running in Docker do not have direct access to a persistent
-file system to store files or use for storing context data.
-
-FlowFuse includes a File Storage service that can be enabled to provide persistent
-storage.
-
-#### Disabling the default File nodes
-
-To remove the default Node-RED file nodes from the palette:
-
-1. Edit the Template to add `10-file.js,23-watch.js` to the "Exclude nodes by filename" section
-
-<img src="../images/file-node-template.png" width=500 />
-
-
-#### Configuring the File Storage service
-
-Full details on configuring the file storage service are available [here](../file-storage/).
-
-#### Enabling the File Storage service
-
-Docker Compose file enables FlowFuse File Storage component by default, no additional actions are required in this area.
-
 ## Upgrade
 
+**Note: If you are upgrading from version `2.9.0` or lower, please follow [this guide](https://github.com/FlowFuse/docker-compose/blob/main/UPGRADE.md)**
+
 1. Find the Docker Compose project name:
     ```bash
     docker compose ls
@@ -209,21 +236,72 @@ Docker Compose file enables FlowFuse File Storage component by default, no addit
 3. Download the latest Docker Compose files:
     ```bash
     curl -o docker-compose.yml https://raw.githubusercontent.com/FlowFuse/docker-compose/refs/heads/main/docker-compose.yml
-    curl -o docker-compose-tls.override.yml https://raw.githubusercontent.com/FlowFuse/docker-compose/refs/heads/main/docker-compose-tls.override.yml
     ```
-4. Make sure the `.env` file is present and contains your installaction-specific configuration
-5. Start the project depending on the TLS configuration (replace `$projectName` with your project name):
-
-  - no TLS:
+4. Make sure the `.env` file is present and contains your installaction-specific configuration. Download an example `.env` file if needed:
     ```bash
-    docker compose -p $projectName up -d
+    curl -o .env.example https://raw.githubusercontent.com/FlowFuse/docker-compose/refs/heads/main/.env.example
     ```
+5. Start the project depending on the TLS configuration (replace `$projectName` with your project name):
+
   - automatic TLS:
     ```bash
-    docker compose -f docker-compose.yml -f docker-compose-tls.override.yml --profile autossl -p $projectName up -d
+    docker compose --profile autossl -p $projectName up -d
     ```
-  - custom TLS:
+  - any other scenario:
     ```bash
-    docker compose -f docker-compose.yml -f docker-compose-tls.override.yml -p $projectName up -d
+    docker compose -p $projectName up -d
     ```
 
+## Common Questions
+
+### How to use external database server?
+
+FlowFuse platform uses PostgreSQL database to store its data. By default, the database is created and managed by the Docker Compose. 
+If you want to use an external database server, you need to:
+* on your database server, create `flowforge` and `ff-context` databases as well as a user with access to both of them (see `configs.postgres_db_setup` and `configs.postgres_context_setup` in the `docker-compose.yml` file for the reference) 
+* configure the connection to the database in the `.env` file. Set the `DB_HOST`, `DB_USER`, `DB_PASSWORD` variables to the connection details of the external database server
+
+Once ready, [start the application](#start-flowfuse-platform) .
+
+### How can I provide my own TLS certificate?
+
+If you have your own TLS certificate, you can use it in FlowFuse platform installation as well. See [Enable HTTPS](#enable-https-optional) section for more details.
+
+### After starting the platform, I can't access it in the browser - I see Connection Refused error
+
+If you are using the Digital Ocean Docker Droplet to host FlowFuse you will need to ensure that port 80 & 443 are opened in the UFW firewall before starting.
+
+FlowFuse platform is running on ports 80 and 443, so you need to open these ports in the firewall. Below are examples of commands to open these ports:
+
+Ubuntu:
+```bash
+sudo ufw apply http
+sudo ufw apply https
+```
+
+CentOS:
+```bash
+sudo firewall-cmd --zone=public --add-service=http --permanent
+sudo firewall-cmd --zone=public --add-service=https --permanent
+sudo firewall-cmd --reload
+```
+
+Windows:
+```bash
+netsh advfirewall firewall add rule name="Open Port 80" dir=in action=allow protocol=TCP localport=80
+netsh advfirewall firewall add rule name="Open Port 443" dir=in action=allow protocol=TCP localport=443
+```
+
+### How can I enable persistent storage for Node-RED instances?
+
+Node-RED instances running in Docker do not have direct access to a persistent file system to store files or use for storing context data.
+
+FlowFuse includes a File Storage service that can be enabled to provide persistent storage.
+
+To disable the default File nodes, edit the Template and add `10-file.js,23-watch.js` to the "Exclude nodes by filename" section
+
+<img src="../images/file-node-template.png" width=500 />
+
+FlowFuse Docker Compose files includes FlowFuse File Storage component by default and starts it along with the platform.
+
+Full details on configuring the File Storage service are available [here](../file-storage/).