From 185c4ad2bdbc2083503645850d5237503d974686 Mon Sep 17 00:00:00 2001 From: Jeff Potts Date: Tue, 29 Jan 2019 07:26:48 -0600 Subject: [PATCH 1/4] Add new file to document upgrade steps The new upgrading.md file documents steps necessary to upgrade from SDK 3.0.1 to SDK 4.0.0. --- docs/advanced-topics/upgrading.md | 192 ++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 docs/advanced-topics/upgrading.md diff --git a/docs/advanced-topics/upgrading.md b/docs/advanced-topics/upgrading.md new file mode 100644 index 00000000..f7a48e4c --- /dev/null +++ b/docs/advanced-topics/upgrading.md @@ -0,0 +1,192 @@ +--- +Title: Upgrading +Added: v4.0.0 +Last reviewed: 2019-01-29 +--- +# Upgrading an SDK 3.0 project to SDK 4.0 + +In these instructions, "base" refers to a freshly instantiated SDK 4.0 and "target" refers to the SDK 3.0.1 project that is being upgraded. + +## Download a base + +Download or instantiate an SDK 4.0 project to use as a base for copying files. + +For example, you might create a new project called "test-aio-400" to use as a base from which to copy files into the target project that is to be upgraded. + +## Remove unnecessary files + +1. Remove the root src directory from the root of the target project. + +2. Remove run.\* and debug.\* from the root of the target project. + +## Copy run scripts from base to target + +1. Copy run.bat and run.sh from base to target project + +## Copy the docker directory from base into target + +1. Recursively copy the docker directory from base into target + +2. Clean up references in the docker-compose.yml file + +In the docker directory copied from the base, edit the docker-compose.yml file to change references to the base project name to the target project name. + +## Copy the platform-docker directory into target + +1. Recursively copy the *-platform-docker directory into target + +2. Rename the directory. The name of the directory should follow the same pattern as the existing project. For example, if the existing project is test-aio-301 then the platform-docker directory should be called test-aio-301-platform-docker. + +## Clean up references in the platform-docker directory in target + +1. If you copied a target directory from the base, remove it. +2. Change references in alfresco-global.properties from the base project name to the target. +3. Change references in pom.xml from the base project name to the target. +4. Change references in hotswap-agent.properties from the base project name to the target. + +## Copy the share-docker directory into target + +1. Recursively copy the *-share-docker directory into target + +Similar to previous step, the directory should follow the same pattern as the existing project. + +## Clean up references in the share-docker directory in target + +1. If you copied a target directory from the base, remove it. +2. Change references in alfresco-global.properties from the base project name to the target. +3. Change references in pom.xml from the base project name to the target. +4. Change references in hotswap-agent.properties from the base project name to the target. + +## Merge the root pom.xml file + +Need to smartly do this merge so that target project maintains its dependencies, name, version, description, etc. + +1. Copy the entire `` element from the base 4.0 pom.xml into the target 3.0 pom.xml, replacing the existing one completely. + +2. Change the `acs.host` property to match the target project name. + +3. Replace the `alfresco-repository` dependency as follows. Change + + + ${alfresco.groupId} + alfresco-repository + + + to: + + + ${alfresco.groupId} + alfresco-remote-api + provided + + +3. Remove the `spring-context` dependency from the target pom.xml: + + + org.springframework + spring-context + 3.2.17.RELEASE + test + + +4. Under dependencyManagement, the platform distribution dependency needs to have its artifactId updated. Change: + + + ${alfresco.groupId} + alfresco-platform-distribution + ${alfresco.platform.version} + pom + import + + + to: + + + ${alfresco.groupId} + ${alfresco.bomDependencyArtifactId} + ${alfresco.platform.version} + pom + import + + +5. The `maven-resources-plugin` needs the outputDirectory adjusted. Change: + + ${project.build.testOutputDirectory} + + to: + + ${project.build.outputDirectory}/docker + +6. Change the `testResources` directory as follows. Change: + + src/test/resources + + to: + + docker + +7. Remove the alfresco-maven plugin. HOWEVER, there may be some "platformModules" and some "shareModules" that are listed here which are third-party AMPs or JARs that need to be deployed to the image. These should be moved to their respective docker module (platform or share) and added to the Maven dependencies in the module's pom.xml file. + +8. Remove the spring-surf dependencies. Remove the following: + + ``` + + org.alfresco.surf + spring-surf + ${alfresco.surf.version} + provided + + + org.alfresco.surf + spring-surf-api + ${alfresco.surf.version} + provided + + ``` + +9. Add the "docker" modules to the list of modules at the end of the pom.xml file. For example, if the target project is named "test-aio-400" the list of modules would be: + + ``` + + test-aio-400-platform-jar + test-aio-400-share-jar + integration-tests + test-aio-400-platform-docker + test-aio-400-share-docker + + ``` + +## Changes to the integration-tests module + +1. Completely replace the pom.xml file with the pom.xml file from the 4.0 pom.xml file under integration-tests. + +2. Edit the integration-tests pom.xml to replace references to the base project name with references to the target project name. + +2. Remove the src/test/properties directory + +3. Remove the src/test/resources directory + +## Changes to the platform-jar module + +Smartly merge the pom.xml file from the 4.0 platform-jar module into the existing platform-jar module pom.xml file. + +Maintain the dependencies from the 3.0 platform-jar module pom.xml. + +Any old "platformModule" dependencies, which are typically AMPs or JARs that need to be installed need to be copied into this pom.xml's dependencies. + +## Changes to the share-jar module + +Smartly merge the pom.xml file from the 4.0 share-jar module into the existing share-jar module pom.xml file. + +Maintain the dependencies from the 3.0 share-jar module pom.xml. + +Any old "shareModule" dependencies, which are typically AMPs or JARs that need to be installed in the Share tier need to be copied into this pom.xml's depdencies. + +Remove the spring-surf-api dependency from the 4.0 share-jar module. Remove: + +``` + + org.alfresco.surf + spring-surf-api + +``` From 5d1fb4f4d9deaa53569c2b5a70577fc0a31ac971 Mon Sep 17 00:00:00 2001 From: Jeff Potts Date: Tue, 29 Jan 2019 13:46:21 +0000 Subject: [PATCH 2/4] Formatting tweaks and example project name change --- docs/advanced-topics/upgrading.md | 80 +++++++++++++++++-------------- 1 file changed, 45 insertions(+), 35 deletions(-) diff --git a/docs/advanced-topics/upgrading.md b/docs/advanced-topics/upgrading.md index f7a48e4c..efcd312e 100644 --- a/docs/advanced-topics/upgrading.md +++ b/docs/advanced-topics/upgrading.md @@ -21,21 +21,21 @@ For example, you might create a new project called "test-aio-400" to use as a ba ## Copy run scripts from base to target -1. Copy run.bat and run.sh from base to target project +1. Copy run.bat and run.sh from base to target project. ## Copy the docker directory from base into target -1. Recursively copy the docker directory from base into target +1. Recursively copy the docker directory from base into target. -2. Clean up references in the docker-compose.yml file +2. Clean up references in the docker-compose.yml file. In the docker directory copied from the base, edit the docker-compose.yml file to change references to the base project name to the target project name. ## Copy the platform-docker directory into target -1. Recursively copy the *-platform-docker directory into target +1. Recursively copy the \*-platform-docker directory into target -2. Rename the directory. The name of the directory should follow the same pattern as the existing project. For example, if the existing project is test-aio-301 then the platform-docker directory should be called test-aio-301-platform-docker. +2. Rename the directory. The name of the directory should follow the same pattern as the existing project. For example, if the existing project is upgrade-test then the platform-docker directory should be called upgrade-test-platform-docker. ## Clean up references in the platform-docker directory in target @@ -46,7 +46,7 @@ In the docker directory copied from the base, edit the docker-compose.yml file t ## Copy the share-docker directory into target -1. Recursively copy the *-share-docker directory into target +1. Recursively copy the \*-share-docker directory into target Similar to previous step, the directory should follow the same pattern as the existing project. @@ -67,47 +67,57 @@ Need to smartly do this merge so that target project maintains its dependencies, 3. Replace the `alfresco-repository` dependency as follows. Change - - ${alfresco.groupId} - alfresco-repository - + ``` + + ${alfresco.groupId} + alfresco-repository + + ``` to: - - ${alfresco.groupId} - alfresco-remote-api - provided - + ``` + + ${alfresco.groupId} + alfresco-remote-api + provided + + ``` 3. Remove the `spring-context` dependency from the target pom.xml: - - org.springframework - spring-context - 3.2.17.RELEASE - test - + ``` + + org.springframework + spring-context + 3.2.17.RELEASE + test + + ``` 4. Under dependencyManagement, the platform distribution dependency needs to have its artifactId updated. Change: - - ${alfresco.groupId} - alfresco-platform-distribution - ${alfresco.platform.version} - pom - import - + ``` + + ${alfresco.groupId} + alfresco-platform-distribution + ${alfresco.platform.version} + pom + import + + ``` to: - - ${alfresco.groupId} - ${alfresco.bomDependencyArtifactId} - ${alfresco.platform.version} - pom - import - + ``` + + ${alfresco.groupId} + ${alfresco.bomDependencyArtifactId} + ${alfresco.platform.version} + pom + import + + ``` 5. The `maven-resources-plugin` needs the outputDirectory adjusted. Change: From 42dc3659bd11d2fcaa70eb2476ca8d1b2b8e71f6 Mon Sep 17 00:00:00 2001 From: Jeff Potts Date: Tue, 29 Jan 2019 14:04:05 +0000 Subject: [PATCH 3/4] Add more details around platform module and share module dependencies. Add a blurb about deleting alf_data_dev. Add a short section on how to test. --- docs/advanced-topics/upgrading.md | 56 +++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/docs/advanced-topics/upgrading.md b/docs/advanced-topics/upgrading.md index efcd312e..ef4637ad 100644 --- a/docs/advanced-topics/upgrading.md +++ b/docs/advanced-topics/upgrading.md @@ -137,6 +137,54 @@ Need to smartly do this merge so that target project maintains its dependencies, 7. Remove the alfresco-maven plugin. HOWEVER, there may be some "platformModules" and some "shareModules" that are listed here which are third-party AMPs or JARs that need to be deployed to the image. These should be moved to their respective docker module (platform or share) and added to the Maven dependencies in the module's pom.xml file. +For example, in the root pom.xml of the target project there might be a module dependency in the list of platform modules like: + +``` + + + de.fmaul + javascript-console-repo + amp + 0.7-SNAPSHOT + +``` + +That needs to be moved to the platform docker module into the list of dependencies, like: + +``` + + + de.fmaul + javascript-console-repo + amp + 0.7-SNAPSHOT + +``` + +Similarly, if the target pom.xml has a share module dependency like: + +``` + + + de.fmaul + javascript-console-share + amp + 0.7-SNAPSHOT + +``` + +Then that would need to be moved into the share docker module's pom.xml file in its list of dependencies like: + +``` + + + de.fmaul + javascript-console-share + amp + 0.7-SNAPSHOT + +``` + 8. Remove the spring-surf dependencies. Remove the following: ``` @@ -200,3 +248,11 @@ Remove the spring-surf-api dependency from the 4.0 share-jar module. Remove: spring-surf-api ``` + +## Remove alf_data_dev + +The data in your SDK content repository will not come over to the upgraded project. Therefore the alf_data_dev directory can be deleted. + +## Testing + +To test, try doing a `mvn clean` or a `mvn clean package`. If that goes okay, try to run the project using `run.sh build_start`. From ef59a6a39ab7aa63f1e18059c10e72d0c9858206 Mon Sep 17 00:00:00 2001 From: jpotts Date: Tue, 29 Jan 2019 14:16:41 +0000 Subject: [PATCH 4/4] Add step to clean up project name references in run.sh and run.cmd --- docs/advanced-topics/upgrading.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/advanced-topics/upgrading.md b/docs/advanced-topics/upgrading.md index ef4637ad..47177c29 100644 --- a/docs/advanced-topics/upgrading.md +++ b/docs/advanced-topics/upgrading.md @@ -23,6 +23,10 @@ For example, you might create a new project called "test-aio-400" to use as a ba 1. Copy run.bat and run.sh from base to target project. +## Clean up the references in the copied scripts + +The run.bat and run.sh scripts have references to the project name. Edit these to change the references that use the base project name to the target project name. + ## Copy the docker directory from base into target 1. Recursively copy the docker directory from base into target.