Ported the Platform repository to use the XTC Plugin, internal versio…

…n 0.4.44, as published on the GitHub Org XVM Maven Package Repository.

.gitignore

@@ -1,14 +1,16 @@
-# Logs and databases #
-######################
+#
+# Logs and databases 
+#
 *.log
 *.out
 *.tmp
 *.temp
 *.sql
 *.sqlite
 
+#
 # OS generated files #
-######################
+#
 .DS_Store
 .DS_Store?
 ._*
@@ -17,20 +19,36 @@
 ehthumbs.db
 Thumbs.db
 
-# build directory #
-###################
+#
+# Build directories
+#
 build/
+
+#
+# Module aggregation directory:
+#
+# While we can still collect everyting into a common lib folder, as a final build step,
+# if we want, the 'standard' Maven style way would be to just build and run the project.
+# Every component declaratively states its dependencies to build and/or run, and any
+# task using these dependencies gets them lazily resolved, and exactly what it needs,
+# nothing more. We will likely implement a distribution config for XTC applications
+# like this, of course, so that the old "lib" folder is some kind of versioned
+# publishable artifact)
+#
 lib/
 
-# xdk directory #
-###################
+#
+# XDK directory
+#
 xdk/
 
-# user-specific project files #
-###############################
+#
+# User-specific project files
+#
 prj/
 .idea/
 
-# Gradle-specific project files #
-#################################
-.gradle
+#
+# Gradle caches
+#
+.gradle

Dockerfile

@@ -49,4 +49,4 @@ RUN mkdir -p ~/xqiz.it/platform \
     && cd ~/xtc_platform && ~/xvm/gradlew build
 
 WORKDIR /root/xtc_platform
-CMD ["xec", "-L", "lib/", "lib/kernel.xtc", "qwerty"]
+CMD ["xec", "-L", "lib/", "lib/kernel.xtc", "qwerty"]

README.md

@@ -1,101 +1,201 @@
-# Platform as a Service #
+# Platform as a Service
 
 This is the public repository for the open source Ecstasy PaaS project, sponsored by [xqiz.it](http://xqiz.it).
 
-## Status:
-
-This project is being actively developed, but is not yet considered a production-ready release.
-
 ## Layout
 
 The project is organized as a number of sub-projects, with the important ones to know about being:
 
-* The *common* library (`./common`), contains common interfaces shared across platform modules. 
-
-* The *kernel* library (`./kernel`), contains the boot-strapping functionality. It's responsible for starting system services and introducing them to each other. 
-
-* The *host* library (`./host`), contains the manager for hosted applications.
+* The *common* library ([platform/common](./common)), contains common interfaces shared across platform modules.
+
+* The *kernel* library ([platform/kernel](./kernel)), contains the boot-strapping functionality. It's responsible for
+  starting system services and introducing them to each other.
+
+* The *host* library ([platform/host](./host)), contains the manager for hosted applications.
 
-* The *platformDB* library (`./platformDB`), contains the platform database. 
+* The *platformDB* library ([platform/platformDB](./platformDB)), contains the platform database.
+
+* The *platformUI* library ([platform/platformUI](./platformUI)), contains the end-points for the platform
+  web-application.
 
-* The *platformUI* library (`./platformUI`), contains the end-points for the platform web-application. 
-
 ## Installation
 
 1. Please follow steps 1-3 of the [XDK Installation](https://github.com/xtclang/xvm#installation).
-2. Clone [the platform repository](https://github.com/xtclang/platform) to your local machine. For purposes of this document, we will assume that the project directory is `~/Development/platform/`, but you may use whatever location makes sense for your environment.
+2. Clone [the platform repository](https://github.com/xtclang/platform) to your local machine.
 
 ## Steps to test the PAAS functionality:
 
-Note that steps 2 and 3 are temporary, and step 3 needs to be re-executed every time after an OS reboot.
+### Provide properties named `gitHubUser` and `gitHubPassword`
+
+The platform expects to be able to read artifacts from the GitHub Maven Package Repository,
+and requires credentials to do so. Later we will have this repo retrieve its artifacts from
+gradlePluginPortal and mavenCentral. To understand how to set up these credentials, follow
+the instructions in the [xtc-template-app](https://github.com/xtclang/xtc-app-template/blob/master/README.md)
+and if you want to get more detail on this, take a look at the comment in the 
+[xtc-template-app settings](https://github.com/xtclang/xtc-app-template/blob/master/settings.gradle.kts)
+
+Hence, ensure that you have properties named "gitHubUser" and "gitHubToken" set up in your
+environments, and that the token has read:package privileges for the GitHub Maven Repo. 
 
-1. Create "xqiz.it" subdirectory under the user home directory for the platform persistent data. The subdirectory "platform" will be used to keep the platform operational information and subdirectory "users" for hosted applications.
+If you can build and run the [xtc-template-app](https://github.com/xtclang/xtc-app-template/tree/master), and 
+have that correctly configured, you can skip this step.
 
-2. Create a file "~/xqiz.it/platform/port-forwarding.conf" with the following content:
+### Create a local (or containerized) platform environment
 
-       rdr pass on lo0 inet proto tcp from any to self port 80  -> 127.0.0.1 port 8080
-       rdr pass on lo0 inet proto tcp from any to self port 443 -> 127.0.0.1 port 8090
+Note that steps 1 and 2 are temporary, and step 2 needs to be re-executed every time after an OS reboot. Steps 3-8 need
+to be done just once. Or Dockerize and never have to think about this again,
+
+1. Create `xqiz.it` subdirectory under the user home directory for the platform persistent data. The subdirectory "
+   platform" will be used to keep the platform operational information and subdirectory "users" for hosted applications.
+
+2. Create a file `~/xqiz.it/port-forwarding.conf` with the following content:
+
+```
+   rdr pass on lo0 inet proto tcp from any to self port 80  -> 127.0.0.1 port 8080
+   rdr pass on lo0 inet proto tcp from any to self port 443 -> 127.0.0.1 port 8090
+```
 
 3. Run the following command to redirect http and https traffic to unprivileged ports:
-
-       sudo pfctl -evf ~/xqiz.it/platform/port-forwarding.conf
+
+```
+   sudo pfctl -evf ~/xqiz.it/platform/port-forwarding.conf
+```
 
 4. Make sure you can ping the local platform address:
-
-       ping xtc-platform.localhost.xqiz.it
-
-   The domain name `xtc-platform.localhost.xqiz.it` should resolve to `127.0.0.1`. This allows the same xqiz.it cloud-hosted platform to be self-hosted on the `localhost` loop-back address, enabling local and disconnected development.
 
-   If that address fails to resolve you may need to change the rules on you DNS server. For example, for Verizon routers you would need add an exception entry for "127.0.0.1" to your DNS Server settings: "Exceptions to DNS Rebind Protection" (Advanced - Network Settings - DNS Server)   
+```
+   ping xtc-platform.localhost.xqiz.it
+```
+
+   The domain name `xtc-platform.localhost.xqiz.it` should resolve to `127.0.0.1`. This allows the same xqiz.it
+   cloud-hosted platform to be self-hosted on the `localhost` loop-back address, enabling local and disconnected
+   development.
+
+   If that address fails to resolve you may need to change the rules on you DNS server. For example, for Verizon routers
+   you would need add an exception entry for `127.0.0.1` to your DNS Server settings: "Exceptions to DNS Rebind
+   Protection" (Advanced - Network Settings - DNS Server)
 
-5. Make sure you have the latest [gradle](https://gradle.org/), [node](https://nodejs.org/en), [yarn](https://yarnpkg.com/) and  [xdk-latest](https://github.com/xtclang/xvm#readme) installed. If you are using `brew`, you can simply say: 
-
-        brew install gradle node yarn  
+5. Create a self-signed certificate for the platform web server. For example:
 
-6. Change your directory to the `./platformUI/gui` directory inside the local git repo installed above.
+```
+    keytool -genkeypair -alias platform -keyalg RSA -keysize 2048 -validity 365 -dname "OU=Platform, O=[your name], C=US" -keystore ~/xqiz.it/platform/certs.p12 -storetype PKCS12 -storepass [password]
+```
 
-        cd ~/Development/platform/platformUI/gui
+6. Add a symmetric key to encode the cookies:
 
-7. Make sure all necessary *node* modules are installed within that directory using the following command:
+```
+    keytool -genseckey -alias cookies -keyalg AES -keysize 256 -keystore ~/xqiz.it/platform/certs.p12 -storetype PKCS12 -storepass [password]
+```
 
-        npm install
+7. If you want to run with an XDK installation and not just let the plugin sort it out, make sure you
+   have [xdk-latest](https://github.com/xtclang/xvm#readme) installed.
 
-8. If you plan to use `quasar` dev environment, please install it globally by the following command:
+8. Make sure you have a Java runtime installed for bootstrapping. It should really be enough with any
+   old Java, just so that you can run the Gradle wrapper. The Java toolchains support should download the
+   latest compatible JDK environment for you, to build and run the XTC Platform.
 
-        npm install -g @quasar/cli
-
-9. Build the platform services using the gradle command (from within the "platform" directory):
+9. Make sure that when you issue Gradle commands, you do it either through the Gradle wrapper script, or from
+   inside your IDE, that you are sure knows about your wrapper script. Any IDE in which you import this project
+   should pick that up and grab the appropriate runtimes and dependencies.
 
-       cd ~/Development/platform/
-       gradle clean build
+   *It is recommended that you *do not* keep a Gradle executable on your system path to build the project, but 
+   instead use the Gradle wrapper script (or its IDE integration) for every task you want to execute.* 
 
-10. Start the platform using the command (from within the "platform" directory):
+10. Build and run the server.
 
-        xec -L lib/ lib/kernel.xtc password
+    You can provide the password for your keystore as a Gradle property, by adding a line on the form
+    `keystorePassword=<your-password>` to the `$GRADLE_USER_HOME/gradle.properties`. This is 
+    the customary way to add secrets outside source control. You can also place it in the environment
+    variable `ORG_GRADLE_PROJECT_password`, or send it as a Gradle property on the launcher line, like this:
 
-    Note: The password you choose during the very first run will be used to encrypt the platform key storage. You will need the same password for all subsequent runs.  
+    * Note: The password you choose during the very first run will be used to encrypt the platform key storage.
+      You will need the same password for all subsequent runs. If you do not provide a password, executing
+      the launcher through one of the two methods described in this paragraph, will prompt for the password
+      on `stdin`, which, while it works, is not compatible with scenarios like automatic CI/CD testing. 
+
+Either build and run the server "the traditional way" (requires a local XDK installation) with: 
+
+```
+    ./gradlew build
+    xec --verbose -L ./build/platform/ kernel.xqiz.it 
+```
+     
+or with the experimental: 
+
+```
+    ./gradlew run -PkeystorePassword=<your secret password>`
+```
+
+Note: the ./gradlew run task described in this paragraph is not meant as a production way of running
+the platform. However, it can be quite handy to use for debugging purses, with "fork=false" in its
+xtcRun configuraiton. That way you can just execute the run task from IntelliJ in Debug mode, and
+just step into your executing platform server.
 
-11. Open the [locally hosted platform web page](https://xtc-platform.localhost.xqiz.it): 
+TODO: ORG_GRADLE_PROJECT_keystorePassword=<your secret password> xec -L ./build/platform/ kernel
 
-        https://xtc-platform.localhost.xqiz.it
+11. Open the [locally hosted platform web page](https://xtc-platform.localhost.xqiz.it):
 
-    Note: Using the locally-created (self-signed) certificate from step 5 above, you will receive warnings from the browser about the unverifiability of the website and its certificate.
+    Note: Using the locally-created (self-signed) certificate from step 5 above, you will receive warnings from the
+    browser about the unverifiability of the website and its certificate.
 
 12. Follow the instructions from the [Examples](https://github.com/xtclang/examples) repository to build and "upload" a web application.
 
 13. Log into the "Ecstasy Cloud" platform using the pre-defined test user "[email protected]" and the password "password".
 
 14. Go to the "Modules" panel and install any of the example module (e.g. "welcome.examples.org").
 
-15. Go to the "Application" panel, register a deployment (e.g. "welcome") and "start" it  
+15. Go to the "Application" panel, register a deployment (e.g. "welcome") and "start" it
 
 16. Click on the URL to launch your application web page.
 
-17. To stop the server cleanly, from a separate shell run this command:
+17. To stop the server cleanly, from a separate shell or process, run this command:
+
+```
+    curl -k -b cookies.txt -L -i -w '\n' -X POST https://xtc-platform.localhost.xqiz.it/host/shutdown
+```
+
+If you do not stop the server cleanly, the next start-up will be much slower, since the databases on the server will
+need to be recovered.
+
+### Third Part Installation Dependencies
+
+Previously, to build and run, we required that NodeJS, NPM and Yarn were installed, and available in the
+environment and PATH on the system where you execute the platform build and/or run. This is problematic 
+since you may have several different applications that you work on that require different versions of
+the software. It's problematic to have to switch between different versions of an external software
+installation, and there are even meta-frameworks like NVM to do that, but it adds complexity, and
+it's hard to always detect that you are running the right version.
+
+It is even more problematic if you have to install or configure  the dependent software with root/admin
+privileges, since this alters the global state of your development machine, perhaps breaking something
+else you need to work on as well.
+
+Luckily, this is 2024, and it's industry best practice to keep exactly versioned dependencies referenced
+and resolvable inside the scope of a project. For those dependencies that still have to live as installed 
+system executables, we containerize.
+
+For the Platform, you don't need to install any additional software as long as you have a bootstrap
+Java runtime for the Gradle wrapper. The Platform project will make sure that it downloads and uses
+the correct and tested versions of its external dependencies. This includes NodeJS and all the other
+things required to build the frontend. The build will always resolve and execute a specific version 
+of an artifact, without any need for configuration. The build will always override any system
+installation of its dependencies with its own, of a known and tested version and configuration.
+
+#### Quasar
+
+While the default behavior is to only install external software dependency at the XTC platform project repo
+level, and in the system Gradle caches, e.g. under $GRADLE_USER_HOME/..., Quasar may still be installed by
+the build as a "global" scope Node application. This should not be necessary for basic use cases, but since
+previous XTC Platform repository supported this option, and we strive to preserve exact semantics of a
+build or system, even when performing large changes, it is supported by the build, through the property:
+
+       org.lang.platform.quasarGlobal=[true|false] 
 
-        curl -k -b cookies.txt -L -i -w '\n' -X POST https://xtc-platform.localhost.xqiz.it/host/shutdown
+If the property is not defined, it will default to "false".
 
-    If you do not stop the server cleanly, the next start-up will be much slower, since the databases on the server will need to be recovered.
+As with all other Gradle properties, the installation mode for Quasar can be declared on the Gradle wrapper
+command line, or in a gradle.properties file in the root of the repository, or under your GRADLE_USER_HOME
+directory.
 
 ## License
 

bin/stop-server.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+curl -k -b cookies.txt -L -i -w '\n' -X POST https://xtc-platform.localhost.xqiz.it/host/shutdown