This tutorial will show you how to get ACS up and running on your Windows machine using the Maven SDK. It will also guide you through setting up the following components:
- Java
- Maven
- Docker
- IDE (here Visual Studio Code)
- Debugger
At the end you will have a running instance of ACS complete with debugger, on which you can then expand.
In order to be able to complete this tutorial you will need to have:
- Windows 10
- At least 8GB of FREE RAM (16GB machine recommended)
A quick note on the links before we begin: They are set up to open a new tab on click.
Installing Java and Maven globally
After completing this section you will be able to execute Java and Maven commands from anywhere on your system, that’s what is meant by installing them globally, but first you'll need to download them.
If you already have Java and Maven installed you can skip this section, however know the minimum requirements would be Java 11 and Maven 3.5.0.
Take the “Windowsx64 Installer” of Java, then download the “Binary zip archive” of Maven and put them into a folder like “users/user/tools/”.
Once you’ve done that you have to tell Windows that they’re available to use. Do this by pressing the “Windows”- key and search for “View advanced system settings”.
Then select “Environment Variables” and click “New” under “System variables”. Call your new variable “JAVA_HOME” and select the path you chose to save the JDK (Java Development Kit). This will give Windows a shortcut that you will use later.
Secondly you’ll need the variable for Maven, for that create a new one and call it “MAVEN_HOME” then let it trace to your Maven repository.
So far you have only created shorthands for the actual paths of the applications, now you need to tell Windows to use them. For that click “Path” under “System variables” and “Edit”.
Create two new Path- variables: “%JAVA_HOME%\bin” and “%MAVEN_HOME%\bin”.
If everything is set up correctly you should now be able to check the version of both Maven and Java from your cmd terminal by executing mvn -v and java -version. It should look like this:
Installing Docker
Docker is paramount, as it provides the environment for ACS to run in, using so-called “Containers”.
First, download “Docker Desktop” and execute the .exe file. Then look for the Docker
When Docker is first installed Windows actually grants it only a very limited amount of memory, so head over to “Resources” and pull the slider for “Memory” to at least 8GB.
Docker is now ready to roll.
If you want to know more about Docker click here. Note, that you have to deploy a container with the tutorial. You’ll find the instructions to do so on the bottom left of the site.
Setting up the IDE
There are tons of great IDE’s out there but we recommend you take Visual Studio Code as this is what we will be using throughout this guide.
To have an easier time writing structured and color coded code, it’s also a good idea to install the extension packs for Java, Maven and XML.
We recommend the linked ones above, but if you want to browse for different ones click the “Extensions”
Setting up a project using the Maven SDK
First off, SDK stands for Software Development Kit and is going to help you get a working base Alfresco extension project up and running including the necessary folder structure and dependencies.
How that base project looks like depends on the Maven archetype you’re telling the SDK to use. Archetypes are basic preset project structures on which you can then expand. ACS provides a number of them, but for this and following tutorials we will use the “All-In-One-Archetype”.
All-In-One means your project will have everything necessary to start development. If you want to know more about it click here.
So let’s get started: Open a cmd terminal and navigate to the location you want your project to be living in.
Next, type in “mvn archetype:generate -Dfilter=org.alfresco:”, this command will cause Maven to scour all available Archetypes and filter them for org.alfresco. It will come up with a total of 6, but as discussed earlier we will go with the “All-In-One-Archetype”, so type in the appropriate number(probably 2 but double check just to make sure).
Once you’ve done that Maven is going to ask you which version of the SDK you want to use, this Tutorial will assume v4.1.0 as it’s the latest at the time of release.
Next, give your project a groupId like “com.myinc” and an artifact- name, let’s keep it simple and use “tutorial” for that.
Lastly Maven is going to ask you to define a value for your groupId, but you can just hit enter as this is only meant for use cases where the namespace of the project differs from your groupId.
Now all you have to do is confirm your properties and you are good to go. From here on in you can actually use the integrated terminal of VS Code. You can find it in the lower half of the screen, where there’ll be a tab called “Terminal” if you can’t find it, drag up the bar at the bottom of the screen.
Now you can start your ACS instance using the SDK by simply running “./run.bat build_start”. Once it’s started successfully you can access Share at http://localhost:8080/alfresco and http://localhost:8180/share.
You are now all set to customize ACS and Share!
Setting up a debugger
One thing you should consider is setting up a debugger as it will make the process of debugging a lot easier.
The basic idea behind this is that when all is said and done you will be able to pause the execution of your code at any time you choose using breakpoints.
The advantage here is that you can check the state of all your instances and variables at any given time, which is an invaluable tool.
First you have to start up ACS, to be able to do that you have to tell Maven to build “target”- directories. These will be used by Docker to launch ACS. Execute mvn install -DskipTests in the terminal.
Once the directories are successfully built, execute ./run.bat build_start. This will get Alfresco Share up and running for you to access, but more on that in later tutorials.
Next hit run in the nav bar at the top of the screen then click Add Configuration! There should be a new file called launch.json now. Edit it so that it looks like this:
{
// Use IntelliSense to learn about possible attributes.
// Hover to view descriptions of existing attributes.
// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
"version": "0.2.0",
"configurations": [
{
"type": "java",
"name": "Debug (Attach) - Remote",
"request": "attach",
"hostName": "localhost",
"port": "8888"
}
]
}So what did you just do?
You basically told Visual Studio Code to attach the debugger for your ACS instance running inside Docker to your localhost on port 8888.
To use your debugger you need to start it up so click run and Start Debugging.
This tutorial will keep the introduction to debuggers very general so if you want to use it in an a bit more complex use case we suggest you try out our advanced Contract-Management-series.
The first thing you need is executable code, luckily there is webscript using a Java class in “tutorial-plattform/src/main/java/com/alfresco/plattformsample”, open it.
Now we are going to add a simple for loop just to demonstrate the basic features of a debugger, so add the following to the executeImpl() method:
for (int i = 0; i < 3; i++){
System.out.println(i);
}Now hover over the space on the left of the line number you put your loop in, there should be a transparent red dot now, which turns opaque when you click it. Congratulations, you officially set up a breakpoint, let’s use it.
Open your browser and visit http://localhost:8080/alfresco/s/sample/helloworld! If everything works correctly your site won’t finish loading, this is due to your breakpoint pausing the execution of the webscript.
Go back to VS Code and, if you are not already there, click on the Run
Okay so what is happening here? On the right side you see your Java class with the line marked where you set the breakpoint, which means the last line executed is the one above, that’s important to remember. On the left you have a list of all your objects and variables and the states they’re in. From what is given here it is not really simple to tell what is going on, but that is why we added the loop. Because if you now hit Step Over
Summary
At this point you should be able to get ACS running using the Maven based Alfresco SDK and have a debugger set up and ready to use.
You can find more information on the Alfresco SDK here.
If you want to know more about how to use ACS we suggest you check out our latest Alfresco Beginner- series, including:
2 Comments
