From 29006d1e934eb787a09dd96d90db03a57a7225a6 Mon Sep 17 00:00:00 2001 From: Jose Luis Osorno Date: Tue, 15 Jan 2019 17:08:58 +0100 Subject: [PATCH] Documentation - Some fixes after review --- docs/debug-intellij.md | 2 +- docs/getting-started.md | 1 + docs/hotswap-agent.md | 14 +++++++------- docs/projects-usage.md | 10 +++++----- docs/structure-aio.md | 2 +- docs/structure-platform.md | 2 +- docs/structure-share.md | 2 +- docs/troubleshooting.md | 14 +++++++------- 8 files changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/debug-intellij.md b/docs/debug-intellij.md index 729667e3..9da1c520 100644 --- a/docs/debug-intellij.md +++ b/docs/debug-intellij.md @@ -72,7 +72,7 @@ You will be taken back to the project source code. ![Alt text](./imgs/sdk-debug-intellij-launch.png?raw=true "IntelliJ remote debug configuration launch") -The IDE connects the source code with the deployed one at the docker container. Once the code it's linked, you can open a browser and start using your +The IDE connects the source code with the deployed one at the docker container. Once the code is linked, you can open a browser and start using your application. In our case, we are going to test the behaviour of debugging by running the sample webscript. 7. Open your browser and type `http://localhost:8080/alfresco/s/sample/helloworld`. diff --git a/docs/getting-started.md b/docs/getting-started.md index c8aea3c8..2ffc2b7d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -199,3 +199,4 @@ In the terminal window, use: If this is the first time you are doing this, it will take a while for Maven to download all the required dependencies and for Docker to download all the required images. +For more information about how to work with the projects, please visit [Working with generated projects](projects-usage.md). diff --git a/docs/hotswap-agent.md b/docs/hotswap-agent.md index d3fc7145..6c70c70c 100644 --- a/docs/hotswap-agent.md +++ b/docs/hotswap-agent.md @@ -23,7 +23,7 @@ and [Docker for Windows](https://docs.docker.com/docker-for-windows/). This is due to an issue with the component used by HotSwapAgent to notify the changes in the compiled class files. HotSwapAgent uses the class [WatcherNIO2.java](https://github.com/HotswapProjects/HotswapAgent/blob/master/hotswap-agent-core/src/main/java/org/hotswap/agent/watch/nio/WatcherNIO2.java) to -watch for the changes in the `extraClasspath` folder. That class is based in the Java class [WatchDir.java](https://docs.oracle.com/javase/tutorial/essential/io/examples/WatchDir.java) +watch for the changes in the `extraClasspath` folder. That class is based on the Java class [WatchDir.java](https://docs.oracle.com/javase/tutorial/essential/io/examples/WatchDir.java) that, in Linux systems, is implemented using [inotify](http://man7.org/linux/man-pages/man7/inotify.7.html). It seems that inotify is not working properly with mounted volumes over Docker Toolbox (which internally uses VirtualBox). @@ -70,7 +70,7 @@ RUN cd /usr/local/tomcat \ ``` 4. Modify the file `docker/docker-compose.yml` to change the ACS container command to avoid the execution of Tomcat with the Security Manager enabled (it makes -the hot reloading tools to fail): +the hot reloading tools fail): ``` sample-project-acs: @@ -109,13 +109,13 @@ For more information about HotSwapAgent configuration for Java 8, please check t ## Configuring HotSwapAgent in the project (Java 11) -Using Java 11 and HotSwapAgent, it isn't necessary to configure the java agent and the alternative JVM as in previous versions. Instead of that, it is required +Using Java 11 and HotSwapAgent, it isn't necessary to configure the java agent and the alternative JVM as in previous versions. Instead, it is required to use an alternative pre-built JDK distribution. That JDK is based on OpenJDK and includes all the required modifications to run the HotSwapAgent properly. In the context of the Alfresco SDK 4.0, this change is an issue because the JDK installation is inherited from the [Alfresco java docker image](https://github.com/Alfresco/alfresco-docker-base-java). It is necessary to modify the project ACS docker image to change the default java installation of the container's OS to the one provided by HotSwapAgent. -A way to implements the required modifications would be: +A way to implement the required modifications would be: 1. Download the last release of the Trava OpenJDK (Linux distribution) from [here](https://github.com/TravaOpenJDK/trava-jdk-11-dcevm/releases) and save it into the folder `PROJECT_ARTIFACT_ID-platform-docker/src/main/docker`. @@ -147,7 +147,7 @@ COPY hotswap-agent.properties $TOMCAT_DIR/webapps/alfresco/WEB-INF/classes ``` 4. Modify the file `docker/docker-compose.yml` to change the ACS container command to avoid the execution of Tomcat with the Security Manager enabled (it makes -the hot reloading tools to fail): +the hot reloading tools fail): ``` sample-project-acs: @@ -182,8 +182,8 @@ the hot reloading tools to fail): ... ``` -Instead of downloading the Trava OpenJDK distribution file and copy it to the container, the Dockerfile script could include directly the download of the file -(via `curl` for instance), but that would slow down the creation of the ACS image each time it is rebuilt. +Instead of downloading the Trava OpenJDK distribution file and copying it to the container, the Dockerfile script could include directly the download of the +file (via `curl` for instance), but that would slow down the creation of the ACS image each time it is rebuilt. ### Creating a custom HotSwapAgent ACS docker image diff --git a/docs/projects-usage.md b/docs/projects-usage.md index 79a94d30..867fda87 100644 --- a/docs/projects-usage.md +++ b/docs/projects-usage.md @@ -5,19 +5,19 @@ Last reviewed: 2019-01-15 --- # Working with generated projects -After generating your project, using one of the Alfresco SDK 4.0 Maven archetypes, it is important to know how to build/run/test these projects. +After generating a project using one of the Alfresco SDK 4.0 Maven archetypes, it is important to know how to build / run / test these projects. The Alfresco Platform 6 deployment architecture is highly based on container technologies, specifically in [Docker](http://docs.alfresco.com/6.0/concepts/master-deploy.html). Due to that, the projects generated using the Alfresco SDK 4.0 archetypes set up their local environment making an intensive use of Docker and Docker compose technologies. -If you're not familiar to these technologies, it is highly recommended visiting the [Docker documentation website](https://docs.docker.com). This site offers +If you're not familiar with these technologies, it is highly recommended visiting the [Docker documentation website](https://docs.docker.com). This site offers a great quantity of training resources about [Docker](https://docs.docker.com/get-started/) and [Docker compose](https://docs.docker.com/compose/gettingstarted/). ## Project structures After generating your project, using one of the Maven archetypes, review the project structure. The directory structure and content of each folder and file -can help you to understand how to start developing with the Alfresco SDK 4.0. Before continuing, make sure that have read and completed the tasks in the +can help you to understand how to start developing with the Alfresco SDK 4.0. Before continuing, make sure that you have read and completed the tasks in the [Getting started](getting-started.md) tutorial. The structure of the project and the purpose of the files it contains vary according to the [Maven archetype](mvn-archetypes.md) used to generate the project @@ -29,7 +29,7 @@ itself. The following links provide detailed descriptions of the different proje ## Run script -All the projects generated using the Alfresco SDK 4.0 archetypes provide an utility script to work with the project. This script is `run.sh` for Unix systems +All the projects generated using the Alfresco SDK 4.0 archetypes provide a utility script to work with the project. This script is `run.sh` for Unix systems and `run.bat` for Windows systems. The execution of this script must be followed by a parameter that dictates the task to be executed in the project. The list of available tasks is: @@ -39,7 +39,7 @@ Task | Description `build_start` | Build the whole project, recreate the ACS and Share docker images, start the dockerised environment composed by ACS, Share, ASS and PostgreSQL and tail the logs of all the containers. `start` | Start the dockerised environment without building the project and tail the logs of all the containers. `stop` | Stop the dockerised environment. -`purge` | Stop the dockerised container and delete all the persistent data (docker volumes). +`purge` | Stop the dockerised environment and delete all the persistent data (docker volumes). `tail` | Tail the logs of all the containers. `reload_share` | Build the Share module, recreate the Share docker image and restart the Share container (not available in the Alfresco Platform JAR archetype). `reload_acs` | Build the ACS module, recreate the ACS docker image and restart the ACS container (only available in the All-In-One archetype). diff --git a/docs/structure-aio.md b/docs/structure-aio.md index 5ae2bc0d..1d16bc58 100644 --- a/docs/structure-aio.md +++ b/docs/structure-aio.md @@ -177,7 +177,7 @@ Alfresco Share client. After this brief introduction of the All-In-One project, let’s focus on the content of the folders. -## Project root +## Project root folder Below is a description of the files in the root of the project (in this case, `my-all-in-one-project`). diff --git a/docs/structure-platform.md b/docs/structure-platform.md index 24fcf73b..315d32dd 100644 --- a/docs/structure-platform.md +++ b/docs/structure-platform.md @@ -89,7 +89,7 @@ Services Repository. After this brief introduction of the Platform JAR project, let’s focus on the content of the folders. -## Project root +## Project root folder Below is a description of the files in the root of the project (in this case, `my-platform-jar-project`). diff --git a/docs/structure-share.md b/docs/structure-share.md index 11fb3deb..d6498a05 100644 --- a/docs/structure-share.md +++ b/docs/structure-share.md @@ -84,7 +84,7 @@ and documentation (`README.md`). After this brief introduction of the Platform JAR project, let’s focus on the content of the folders. -## Project root +## Project root folder Below is a description of the files in the root of the project (in this case, `my-share-jar-project`). diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e2090463..f6c4235d 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -26,22 +26,22 @@ com/example/platformsample/Demo has been compiled by a more recent version of th this version of the Java Runtime only recognizes class file versions up to 52.0 (unable to load class [com.example.platformsample.Demo]) ``` -This error represents that the source code was compiled using a wrong version of the JDK. This issue can happen if the generated project is compiled using +This error represents that the source code was compiled using the wrong version of the JDK. This issue can happen if the generated project is compiled using JDK 11 and it is deployed in an ACS 6.0 container (which uses JRE 8). ### Solution To solve this issue you can follow several approaches: -* Compile the project using a JDK version lower than 11 (and upper or equal 8). +* Compile the project using a JDK version lower than 11 (and equal to or newer than 8). * Remove the `java11` profile in the `pom.xml` file of the base project (this is not recommended if you plan to move to ACS 6.1 in the future). -* Move to ACS 6.1+. This is highly recommended due to it uses JRE 11 (JDK 8 has already reached its end of support time). +* Move to ACS 6.1+. This is highly recommended due to the fact that it uses JRE 11 (JDK 8 has already reached its end of support time). ## Containers synchronization ### Problem -ACS depends on the readiness of the database in order to start properly. If the database is not ready when ACS reach the startup phase that requires it, then -it fails showing some error messages in the log: +ACS depends on the readiness of the database in order to start properly. If the database is not ready when ACS reaches the startup phase that requires it, then +it fails showing error messages in the log: ``` sample-project-acs_1 | Jan 10, 2019 10:58:06 AM org.postgresql.core.v3.ConnectionFactoryImpl log @@ -126,7 +126,7 @@ With this configuration in place, when the project is rebuilt and restarted the The docker-based development environment started by a project generated using the Alfresco SDK archetypes exposes a set of different ports to the hosted machine (i.e. ACS http port, ACS debug port or PostgreSQL port). -If one of these ports is already in use in the hosted machine (by other service) when you start the development environment, then the startup process will fail +If one of these ports is already in use in the hosted machine (by another service) when you start the development environment, then the startup process will fail and the container that wanted to expose the busy port won't start. ### Solution @@ -134,7 +134,7 @@ and the container that wanted to expose the busy port won't start. The docker compose file under `docker/docker-compose.yml` is the source file that, in the compile phase of the project, will be filtered by the `maven-resource-plugin` in order to produce the final copy of the docker compose file. -That allows to modify the number of the exposed ports through maven properties in the `pom.xml` file of the main project. +That allows you to modify the number of the exposed ports through maven properties in the `pom.xml` file of the main project. ```