Document appsody limitations, troubleshooting, and supported types

[sghung]

We need to document all this so the user can find it easily. I will work on the content first and then give to ID for review.

[sghung]

Attach Debugger must be run a second time for microprofile project extensions (eclipse-archived/codewind#239)

[makandre]

Document nodejs and swift templates remain in starting state (no listening server)

[keithchong]

Errors in Eclipse Java Appsody Project after project creation

These apply to both Java MicroProfile and Spring Appsody templates.

• Project build error: Non-resolvable parent POM

To work around this:

1. From the New Codewind Project Wizard, select a Java-based Appsody template.
2. Finish with the wizard
3. Once the project shows up in the Codewind Explorer view, rIght click on the project and select Show Log Files->Show All
4. If your .m2 cache is 'empty' or this is the first time creating a Java Appsody project, you will see that the dependencies are being downloaded. You will also see:
   [Container] Installing parent dev.appsody
5. Wait until this cache is completed. (You can wait until the Liberty defaultServer is started or when the Project status is "Running")
6. Right click on the Project from the Project Explorer and select Maven->Update Project...
7. Accept the defaults and click OK
   ---> The project will be configured and the error Project build error: Non-resolvable parent POM should disappear.

After the initial project is created, and .m2 cache is set up, then this workaround might not be needed. Any subsequent new projects will be configured properly.

• Unknown error on line 1 of pom.xml

If you are using an Eclipse IDE for Enterprise Developer EPP earlier than 2019.06 then you will see am Unknown validation error on the pom.xml. See Cannot import any project into Eclipse with maven-jar-plugin 3.1.2 for workaround. You can also use 2019.06 or later.

[sghung]

Thanks Keith, I have reviewed those steps and confirmed they work

[keithchong]

Appsody project errors in Codewind for VS Code

• Classpath is incomplete warnings or application classes are not on the classpath

1. After creating an Appsody Java Microprofile project ensure that the codewind-workspace is opened
2. Right click on the codewind-workspace folder and select Add Folder to Workspace...
3. Choose the project folder and click Add

• Failed to attach to remote debuggee VM or Failed to attach debugger messages when starting in debug mode

  To Debug:
  1. Right click on the project and select Restart in Debug Mode
     -> You may get one or both of the following error messages:
     Failed to attach to remote debuggee VM
     or
     Failed to attach debugger
     There is an issue for this: [Appsody debug scenario documentation] Attach Debugger must be run a second time for microprofile project extensions codewind#239
  2. Right click on the project and select Attach Debugger

[sishida]

I just noticed this now. I'm going to try to create a PR for this content. Thanks for all the input so far!

[sishida]

Hi, team, I created PR 71 for adding the Appsody content to the Troubleshooting page.

Also...Do we have a workaround for the Node.js and Swift templates remaining in the starting state because they're not attaching to the server?

Thanks!

[sghung]

@sishida no workaround for those projects yet, although I think we should play around with it to actually try to get it to work. I'll get back to you on that, I think its a matter of getting a server up and exposing the proper ports so it can be reached.

If eclipse-archived/codewind#250 gets merged, the status would show as stopped instead of starting, which is more helpful.

Those projects don't expose a port that we can listen to since the user is suppose to do it. These are templates that don't quite work well out of the box in codewind.

[sishida]

@sghung Thanks for the clarification. If you'd like any changes to the PR, please just let me know! :)

[sghung]

@sishida below is an update to the appsody troubleshooting section. Please re-write as you see fit. Here are a few notes:

• For Node.js, there are multiple node.js tempaltes for Appsody, so I think it's worth being specific on which one is problematic, which is "Appsody Node.js template"
• Added that with the PR 250, after a certain duration, the app goes to stopped state
• Added what the workaround is, which is to implement a server yourself if you want to see the server go to a started state

Node.js and Swift templates remain in the starting state
The templates “Appsody Node.js template” and “Appsody Swift template” will go from starting state to stopped state by default. These templates do not have a server and are intended for the user to implement their own server. The application will terminate although the container will still be running. To get the application into a started state, implement a server for the application. Once the application has a server, Codewind can monitor the server, and the status will be started if the server is up.

[sghung]

TODO: need to document MAVEN_OPTS azure scenario

[sishida]

@sghung Please see the latest commit (60938a1) for the latest update to the "Node.js and Swift templates remain in the starting state" section.

Please also let me know if you'd like any more changes. Thanks!

[sishida]

@sghung I see that the PR is merged: #71. Is this issue good to close? If so, could you please close it? Thanks!

[sghung]

Closing since all the appsody troubleshooting has been added.