Upgrading from SDK 3.0.1 to SDK4

[bip1989]

Our team is planning upgrade from ACS 5.2 to ACS 6.2. 

As a first step, we want to upgrade the development framework (sdk). What are the best practices to follow while upgrading from SDK3.x to SDK4.x? 

As a test in simply took base code generated from SDK4 and changed the ACS version to 6.2 but it fails to start, however it works with 6.1. 

Is SDK4 is not yet ready to work with 6.2?

Our plan is to upgrade to 6.2 instead of 6.1

Any guidance is greatly appreciated 

[jljwoznica · Accepted solution]

SDK 4.1 works with ACS 6.2 (https://github.com/Alfresco/alfresco-sdk/blob/master/README.md).

There are some blogs/github projects on upgrading:
https://github.com/Alfresco/alfresco-sdk/blob/sdk-4.0/docs/advanced-topics/upgrading.md

https://github.com/jpotts/alfresco-sdk-upgrader/

[abhinavmishra14 · Accepted solution]

Before going to use SDK4.x you must know about docker, docker-compose, DockerFile etc. You can go through this blog to understand the docker based deployments: https://hub.alfresco.com/t5/alfresco-content-services-blog/deploying-and-running-alfresco-content-se...

You can follow the below given steps:

1- Generate the archetype [ use: mvn archetype:generate -Dfilter=org.alfresco: ] using SDK 4.1.0 (meant for ACS 6.2.0). Decide to generate AIO or individual archetypes based on your current setup/preference. You would get additional project named "yourproject-share-docker/yourproject-platform-docker". It will have DockerFile containing the base image and steps to be performed while launching the containers. You will also get a project named as "docker", this will have docker-compose.yml file which basically defines all the services which using which containers will be launced. 

Make sure you provide the same groupId and artifactId as per your current project. 

To get basic idea of DockerFile, refer: 

https://dzone.com/articles/understanding-dockerfile

https://docs.docker.com/engine/reference/builder/

To get basic idea of docker-compose.yml, refer: https://docs.docker.com/compose/

2- Build and Start the containers and see if everything works ok. Use "run.bat build_start" (run.sh build_start for linux) command to build and start the docker containers. You can refer "run.bat or run.sh" files. 

3- If everything looks good, stop the containers and purge the docker volumes.

4- Copy all the customizations in the newly generated structure. Include all third party or additional dependencies you would have used into the pom file in newly generated projects (*-platform-docker, *-share-docker projects accordingly). You can remove the samples from newly generated structure if you don't need them. Resolve any dependency errors you see any. For example, if you have used commons-lang StringUtils class then you have to update its import to use commons-lang3. Old library is no longer available. If you have used org.alfresco.util.BaseAlfrescoSpringTest for creating your integration tests. Then you need to do some re-work on your test class. You need to start using: "org.alfresco.rad.test.AbstractAlfrescoIT". Same way you may see many other errors/warnings. 

Refer this blog for more details on changes: https://hub.alfresco.com/t5/alfresco-content-services-hub/alfresco-community-edition-6-0/ba-p/291165

5- Make sure that the module.id of existing project matches the module.id of newly generated projects, otherwise you will get error while deploying. if you have used "module.id=${project.artifactId}" in existing project and named the artifactId same as the existing projects then you should not be having any issues.

6- Consider reviewing this document if you have been using transformation service: https://hub.alfresco.com/t5/alfresco-content-services-blog/introducing-alfresco-transform-service-ne...

https://docs.alfresco.com/6.2/concepts/managing-transformations.html

7- After you are done, build and start the docker containers as you did in step 2. Tail the logs to see what all the error/warnings.

8- To remote debug and put breakpoints you can follow these documents. Make sure you add below step in platform DockerFile:

Add the below given line in your platform-docker project's DockerFile:

COPY hotswap-agent.properties $TOMCAT_DIR/webapps/alfresco/WEB-INF/classes

For remote debugging follow the instructions given here: 

Intellij: https://github.com/Alfresco/alfresco-sdk/blob/master/docs/advanced-topics/debugging/debug-...

Eclipse: https://github.com/Alfresco/alfresco-sdk/blob/master/docs/advanced-topics/debugging/debug-eclipse.md

------------------------------------------------------------------------------------------------------------------

Did you use SDK 4.1.0 for getting the base code? ACS6.2 works fine with SDK4.1.0. Based on your inputs looks like you used SDK 4.0.0 instead of SDK 4.1.0, i would suggest to use SDK 4.1.0 for ACS 6.2

Additionally refer these documentations: 

https://www.slideshare.net/angelborroy/2019-dev-con115angelborroy

You can also use : https://github.com/Alfresco/alfresco-docker-installer project created by @angelborroy . Its a nice tool to start with setting up ACS 6.2

[jljwoznica · Accepted solution]

SDK 4.1 works with ACS 6.2 (https://github.com/Alfresco/alfresco-sdk/blob/master/README.md).

There are some blogs/github projects on upgrading:
https://github.com/Alfresco/alfresco-sdk/blob/sdk-4.0/docs/advanced-topics/upgrading.md

https://github.com/jpotts/alfresco-sdk-upgrader/

[abhinavmishra14 · Accepted solution]

Before going to use SDK4.x you must know about docker, docker-compose, DockerFile etc. You can go through this blog to understand the docker based deployments: https://hub.alfresco.com/t5/alfresco-content-services-blog/deploying-and-running-alfresco-content-se...

You can follow the below given steps:

1- Generate the archetype [ use: mvn archetype:generate -Dfilter=org.alfresco: ] using SDK 4.1.0 (meant for ACS 6.2.0). Decide to generate AIO or individual archetypes based on your current setup/preference. You would get additional project named "yourproject-share-docker/yourproject-platform-docker". It will have DockerFile containing the base image and steps to be performed while launching the containers. You will also get a project named as "docker", this will have docker-compose.yml file which basically defines all the services which using which containers will be launced. 

Make sure you provide the same groupId and artifactId as per your current project. 

To get basic idea of DockerFile, refer: 

https://dzone.com/articles/understanding-dockerfile

https://docs.docker.com/engine/reference/builder/

To get basic idea of docker-compose.yml, refer: https://docs.docker.com/compose/

2- Build and Start the containers and see if everything works ok. Use "run.bat build_start" (run.sh build_start for linux) command to build and start the docker containers. You can refer "run.bat or run.sh" files. 

3- If everything looks good, stop the containers and purge the docker volumes.

4- Copy all the customizations in the newly generated structure. Include all third party or additional dependencies you would have used into the pom file in newly generated projects (*-platform-docker, *-share-docker projects accordingly). You can remove the samples from newly generated structure if you don't need them. Resolve any dependency errors you see any. For example, if you have used commons-lang StringUtils class then you have to update its import to use commons-lang3. Old library is no longer available. If you have used org.alfresco.util.BaseAlfrescoSpringTest for creating your integration tests. Then you need to do some re-work on your test class. You need to start using: "org.alfresco.rad.test.AbstractAlfrescoIT". Same way you may see many other errors/warnings. 

Refer this blog for more details on changes: https://hub.alfresco.com/t5/alfresco-content-services-hub/alfresco-community-edition-6-0/ba-p/291165

5- Make sure that the module.id of existing project matches the module.id of newly generated projects, otherwise you will get error while deploying. if you have used "module.id=${project.artifactId}" in existing project and named the artifactId same as the existing projects then you should not be having any issues.

6- Consider reviewing this document if you have been using transformation service: https://hub.alfresco.com/t5/alfresco-content-services-blog/introducing-alfresco-transform-service-ne...

https://docs.alfresco.com/6.2/concepts/managing-transformations.html

7- After you are done, build and start the docker containers as you did in step 2. Tail the logs to see what all the error/warnings.

8- To remote debug and put breakpoints you can follow these documents. Make sure you add below step in platform DockerFile:

Add the below given line in your platform-docker project's DockerFile:

COPY hotswap-agent.properties $TOMCAT_DIR/webapps/alfresco/WEB-INF/classes

For remote debugging follow the instructions given here: 

Intellij: https://github.com/Alfresco/alfresco-sdk/blob/master/docs/advanced-topics/debugging/debug-...

Eclipse: https://github.com/Alfresco/alfresco-sdk/blob/master/docs/advanced-topics/debugging/debug-eclipse.md

------------------------------------------------------------------------------------------------------------------

Did you use SDK 4.1.0 for getting the base code? ACS6.2 works fine with SDK4.1.0. Based on your inputs looks like you used SDK 4.0.0 instead of SDK 4.1.0, i would suggest to use SDK 4.1.0 for ACS 6.2

Additionally refer these documentations: 

https://www.slideshare.net/angelborroy/2019-dev-con115angelborroy

You can also use : https://github.com/Alfresco/alfresco-docker-installer project created by @angelborroy . Its a nice tool to start with setting up ACS 6.2

[sakbar]

Hi Abhinav,

Thanks for your detailed and clear instructions. For our upgrade (SDK 3.0.1 to 4.5.0 and ACS 5.2 to 7.2.3) we deciced to use amps instead of containers, is there anything different we need to do?

We can just follow your instructions execpt just ignore the docker projecrts and uncomment the plugins for amp right?

I woluld really appreciate your input on this.

--Syed.

[jpotts · Accepted solution]

I was on a hack-a-thon team that wrote tool for migrating SDK 3 projects to SDK 4. My blog post describes the tool, links to the GitHub project, and also includes a screencast that shows a demo.

Or, if you want to skip the blog post and the video and go straight to the code, it lives here:

https://github.com/jpotts/alfresco-sdk-upgrader/

Hope that helps,

Jeff

[bip1989]

Hi @jljwoznica @abhinavmishra14 @jpotts

I will go through the links. Its very much helpful. Thank you very much for your response.