Troubleshooting guide

If you encounter issues during the usage of BCD due to a bad configuration or a network problem, it’s interesting to know that you could be able to simply relaunch your command (create, deploy) after fixing the configuration or the network and it should resume from where it was.

InvalidAMIID.NotFound and InvalidSubnetID.NotFound

If while you launch a create command in order to create instances on AWS you get errors like these:

[...]
InvalidAMIID.NotFound: The image id '[ami-fc4f5e85]' does not exist
[...]
Error launching source instance: InvalidSubnetID.NotFound: The subnet ID 'subnet-ab123456' does not exist
[...]

You should check that ec2_subnet_ids and aws_ami correspond to the region set into ec2_region. You may also check that rights linked to your AWS credentials (.boto or .aws) correspond to the actions in your scenario.

Access to private maven repository is denied

In order to configure BCD to use a corporate maven repository, define it as a mirror for maven central Add a regular maven settings.xml file with the proper mirror configuration in /home/bonita/.m2 folder inside bcd controller container:

If you want to update an already running container without restart, you can run the following, otherwise use docker volume binding.

# .m2 folder may be created before
docker cp <PATH-TO-SETTINGS.xml> bcd-controller:/home/bonita/.m2/settings.xml

Restricted Internet access by an enterprise proxy

If required, you can configure BCD to use proxy settings.

This has to be done for the docker container, the maven installation. If you are using the bcd stack commands, you may need to configure ansible as well.

Starting from BCD 3.4, you can directly bind mount your host maven ~/.m2 folder. This will give BCD access to your already configured maven settings (enterprise repository configuration, proxy settings, etc.) and you will also benefit from the already cached artifacts present in your ~/.m2/repository folder.

Accessing Bonita logs

In order to troubleshoot issues you may need to consult Bonita logs.

To do so, first you need to identify the target server where the Bonita container is running. It’s possible through the bcd stack status command:

bcd -s scenarios/myscenario.yml -y stack status

[...]
[10:44:12.802] TASK [List Docker containers.] **************************************************************************************************
[...]
IP: 54.191.90.85
FQDN: ec2-54-191-90-85.us-west-2.compute.amazonaws.com

Docker running containers
--
CONTAINER ID        IMAGE                                  CREATED             STATUS              NAMES
5d73a2446245        bonitasoft/bonita-subscription:7.11.0   6 minutes ago       Up 6 minutes        bonita8081
[...]

Then you will need to connect on this server (either through the IP or FQDN) using ssh.

ssh -i ~/.ssh/my_key.pem ubuntu@54.191.90.85

You can now display the logs using:

docker logs bonita8081

If you want to copy all the logs (bonita, catalina) you can use docker cp:

docker cp bonita8081:/opt/bonita/BonitaSubscription-7.11.0-Tomcat-8.5.34/server/logs/ /tmp/

Then you will be able to retrieve all the files through a scp:

scp -i ~/.ssh/my_key.pem ubuntu@54.191.90.85:/tmp/logs /tmp/

A REST API Extension compilation generates errors

The bcd …​ livingapp build …​ failed to generate the REST API Extensions with these error messages below:

...
[INFO]
[INFO] --- maven-compiler-plugin:3.6.0:compile (default-compile) @ tankLevelRestAPI ---
[INFO] Changes detected - recompiling the module!
[INFO] Using Groovy-Eclipse compiler to compile both Java and Groovy files
[INFO] -------------------------------------------------------------
[ERROR] COMPILATION ERROR :
[INFO] -------------------------------------------------------------
[ERROR] /workspace/CarProject/restAPIExtensions/tankLevelRestAPI/src/main/groovy/com/support/bonitasoft/rest/api/Index.groovy:[1,1] 1. ERROR in /workspace/CarProject/restAPIExtensions/tankLevelRestAPI/src/main/groovy/com/support/bonitasoft/rest/api/Index.groovy (at line 1)
	package com.support.bonitasoft.rest.api;
	^
The type java.lang.Object cannot be resolved. It is indirectly referenced from required .class files

[ERROR] /workspace/CarProject/restAPIExtensions/tankLevelRestAPI/src/main/groovy/com/support/bonitasoft/rest/api/Index.groovy:[1,1] 2. ERROR in /workspace/CarProject/restAPIExtensions/tankLevelRestAPI/src/main/groovy/com/support/bonitasoft/rest/api/Index.groovy (at line 1)
	package com.support.bonitasoft.rest.api;
	^
The type java.lang.String cannot be resolved. It is indirectly referenced from required .class files
...
[ERROR] /workspace/CarProject/restAPIExtensions/tankLevelRestAPI/src/main/groovy/com/support/bonitasoft/rest/api/Index.groovy:[100,61] 21. ERROR in /workspace/CarProject/restAPIExtensions/tankLevelRestAPI/src/main/groovy/com/support/bonitasoft/rest/api/Index.groovy (at line 100)
	resourceProvider.getResourceAsStream(fileName).withStream { InputStream s ->
	                                                            ^^^^^^^^^^^
Groovy:unable to resolve class InputStream

[ERROR] Found 21 errors and 0 warnings.
[INFO] 22 errors
[INFO] -------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
...
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.6.0:compile (default-compile) on project tankLevelRestAPI: Compilation failure: Compilation failure:
[ERROR] /workspace/CarProject/restAPIExtensions/tankLevelRestAPI/src/main/groovy/com/support/bonitasoft/rest/api/Index.groovy:[1,1] 1. ERROR in /workspace/CarProject/restAPIExtensions/tankLevelRestAPI/src/main/groovy/com/support/bonitasoft/rest/api/Index.groovy (at line 1)
[ERROR] 	package com.support.bonitasoft.rest.api;
[ERROR] 	^
[ERROR] The type java.lang.Object cannot be resolved. It is indirectly referenced from required .class files
...
[ERROR] Found 21 errors and 0 warnings.
...
[ERROR] Failed to build /workspace/CarProject/restAPIExtensions/tankLevelRestAPI
java.io.IOException: Maven build failed.
	at com.bonitasoft.la.builder.task.AbstractCustomPageProjectTask.runMavenInstall(AbstractCustomPageProjectTask.java:64)
	at com.bonitasoft.la.builder.task.AbstractCustomPageProjectTask.execute(AbstractCustomPageProjectTask.java:45)
	at com.bonitasoft.la.builder.task.TaskExecutor.lambda$build$0(TaskExecutor.java:37)
	at java.base/java.util.ArrayList$ArrayListSpliterator.forEachRemaining(ArrayList.java:1655)
	at java.base/java.util.stream.ReferencePipeline$Head.forEach(ReferencePipeline.java:658)
	at com.bonitasoft.la.builder.task.TaskExecutor.build(TaskExecutor.java:34)
	at com.bonitasoft.la.builder.BuilderCLI.run(BuilderCLI.java:142)
	at com.bonitasoft.la.builder.BuilderCLI.buildCmd(BuilderCLI.java:126)
	at com.bonitasoft.la.builder.BuilderCLI.main(BuilderCLI.java:82)

The REST API Extension involved was created with a lower version of the Bontia product. There are java librarires (.jar files) which are not compatible with java 11 used with latest version of BCD.

The Maven’s pom.xml file needs to be modified. The versions of the dependency and plugins listed below must be updated:

  • dependency groovy-all

  • plugin maven-compiler-plugin

  • plugin groovy-eclipse-compiler

  • plugin groovy-eclipse-batch

In order to find the versions to use, apply the procédure below:

  • Start the Studio

  • Create a new dummy REST API extension: the new pom.xml file created contains the versions to used

  • Update the pom.xml file of the REST API Extension which failed to be compiled.

Debugging Ansible Facts

Ansible facts are local variables registered in hosts. It is possible to save them in JSON files with the setup command.

$ cd bonita-continuous-delivery
$ bcd -s scenarios/myscenario.yml -y stack create deploy
$ ansible all -vv -i ansible/inventory/ec2/ec2_wrapper.sh -m setup -u ubuntu --private-key=~/.ssh/my_key.pem --tree tmp_facts/

This command will identify every EC2 instance (depending of bcd_stack_id set into ec2.ini by the last bcd stack deploy command) and put its facts into the tmp_facts directory.

Accessing Ansible Logs

In order to troubleshoot issues, you may need to consult Ansible logs.

By default, the path of the log is /var/log/ansible.log in your Docker container. You can change this location modifying the variable log_path in the Ansible configuration file located in /home/bonita/bonita-continuous-delivery/ansible/ansible.cfg.

If you want to persist the log, you can add a volume in when you run docker run command like

$ docker run --rm -t -i --name bcd-controller \
    -v :/home/bonita/.boto \
    -v :/home/bonita/bonita-continuous-delivery \
    -v :/home/bonita/.ssh/ \
    -v :/var/log/ansible.log \
    quay.io/bonitasoft/bcd-controller:3.4.5 /bin/bash

Files owned by another user in the workspace (Linux users only)

BCD is packaged as a docker image, and the user inside the image is mapped to the most common default user id and group id (for the first created user) on linux platform which is 1000

Since BCD creates files during execution, if your user id doesn’t match the user id inside the docker image, you will end with new files under BCD workspace owned by another user than you and won’t be able to edit or delete them unless having admin privileges.

Example: the dependencies folder:

ls -la dependencies/
-rw-r--r-- 1 <my-user-id> <my-group-id>  157 déc.   4  2019 README.md
drwxr-xr-x 2 root   root                 4096 janv. 6  2020 7.11.3 # <= this folder created by BCD is now read only for <my-user>

To properly map your own user to the user inside the BCD controller image, see the Running BCD controller with user ID different from 1000 paragraph in BCD Controller image