README.md - brooklyn-ui - Git at Google

 # [![**Brooklyn**](https://brooklyn.apache.org/style/img/apache-brooklyn-logo-244px-wide.png)](http://brooklyn.apache.org/)

 ### Apache Brooklyn UI Sub-Project

 This repo contains the JavaScript UI for Apache Brooklyn plus server-side code to enable module lookup and discovery.

 Essential contents:

 * `modularity-server`:  Java OSGi modules to facilitate registering and discovering available modules
 * `ui-modules`: Individual Angular JS modules -- each can be run as a standalone Node app,
   or built as OSGi bundle including the WAR to be served collectively by an OSGi server
   (each using the modularity server-side endpoints to find available modules and allow navigation between them,
   and the  `home` module providing a convenient entry point)
 * `features`: Build an OSGi feature


 ### Building the project

 Two methods are available to build this project: within a docker container or directly with maven.

 #### Using docker

 The project comes with a `Dockerfile` that contains everything you need to build this project.
 First, build the docker image:

 ```bash
 docker build -t brooklyn:ui .
 ```

 Then run the build:

 ```bash
 docker run -i --rm --name brooklyn-ui -v ${HOME}/.m2:/root/.m2 -v ${PWD}:/usr/build -w /usr/build brooklyn:ui mvn clean install
 ```

 ### Using maven

 You will need the following binaries installed first:
 * `java`
 * `maven` (please note, you will need version 3.5.2 or later)
 * `git`
 * `bzip2`
 * `libpng`. This has different package names based on the distribution:
   * `libpng-devel` for CentOS
   * `libpng-dev` for Debian/Ubuntu (also requires `libpng12`)
   * `libpng` for MacOS

 _Optional, if the `libpng` cannot be found when building (package names may vary; often these are not required):_
 * `libpng` (or `libpng-devel` on CentOS, `libpng-dev` on Debian/Ubuntu, `libpng12` sometimes)
 * _`automake (opt)`_
 * _`autoconf`_
 * _`libtool`_
 * _`dpkg`_
 * _`pkgconfig`_
 * _`nasm`_
 * _`gcc`_
 * _`build-essential`_
 * `bzip2`
 * _`pngquant`_
 * _`libfontconfig1-dev`_

 With this, simply run:

 ```bash
 mvn clean install
 ```


 ## Dev

 Instructions for developing UI modules is included in subdirectories, but in short all you need to do once things are configured
 is to run `make` in the relevant module directory, with a Brooklyn REST server on 8081.


 ## Documentation

 For developers, the following links may be useful:

 * [Overview and architecture of the project](docs/overview.md)
 * [Building individual module / Dev environment](ui-modules/README.md)
 * [Skinning the UI with custom themes](docs/skinning.md)
 * [Customizing and embedding the UI](docs/customizations.md)


 ## Troubleshooting

 ### Build Failure (Cached Dependencies)

 The first time `mvn clean install` or `yarn run build` is run, it will cache dependencies in `node_modules`.
 If a dependency is subsequently upgraded, this could cause an incompatibility. For example, it can cause
 a test failure such as:

     20 06 2018 17:28:41.143:ERROR [karma]: { Error: spawn ENOTDIR
         at ChildProcess.spawn (internal/child_process.js:357:11)
         at spawn (child_process.js:528:9)
         at spawnWithoutOutput (/Users/aledsage/repos/apache/brooklyn/brooklyn-ui/ui-modules/utils/node_modules/karma/lib/launchers/process.js:141:24)

 The fix is to delete the auto-generated `node_modules` directories:

 ```bash
 cd /path/to/brooklyn_ui
 find ./ -type d -name "node_modules" -exec rm -rf {} \+
 ```

 ### Errors with libpng

 On many systems the `imagemin` dependency of JS shows errors during install, often due to `libpng` missing
 or the `jpeg` compilation failing (note this one can be a non-fatal error at the time, but the build will then fail).

 Consult the list above of dependencies to install, and make sure you wipe the `node_modules` dirs.

 If libpng still seems to be missing and you are using an M1 Mac then the following lines may help.

 ```bash
 arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
 arch -x86_64 /usr/local/bin/brew install libpng
 ```

 This installs th x86 version of brew and uses that to install the x86 version of the libpng library.  This won't affect your arm64 brew or anything installed using it.

 If it still fails, try installing `nvm` (curl-to-bash) then `nvm ls-remote` and `nvm install v12.9.0` (or other latest).
 Then retry the `mvn` build; even though `mvn` uses a different version of `node` and `yarn`, simply installing the latest
 node version sometimes sorts out errors.


 ### Docker Build Failure (Dependencies for Wrong Architecture)

 When the build is run locally, it will download executables such as `phantomjs`, for the
 local architecture. If the build is subsequently run in a Docker container, mounting the
 local repo directory, it may be incompatible. An example error is:

 ```
 [INFO] 25 06 2018 15:26:48.224:ERROR [launcher]: PhantomJS stdout:
 [INFO] 25 06 2018 15:26:48.224:ERROR [launcher]: PhantomJS stderr: /usr/build/ui-modules/utils/node_modules/phantomjs-prebuilt/lib/phantom/bin/phantomjs: 1: /usr/build/ui-modules/utils/node_modules/phantomjs-prebuilt/lib/phantom/bin/phantomjs: Syntax error: Unterminated quoted string
 ```

 You can check the file type by running:

 ```bash
 file ./ui-modules/utils/node_modules/phantomjs-prebuilt/lib/phantom/bin/phantomjs

 ./ui-modules/ui-utils/node_modules/phantomjs-prebuilt/lib/phantom/bin/phantomjs: Mach-O 64-bit executable x86_64
 ```

 The fix is to delete the auto-generated `node_modules` directories:

 ```bash
 cd /path/to/brooklyn_ui
 find ./ -type d -name "node_modules" -exec rm -rf {} \+
 ```

 ### Test Failure (PhantomJS)

 Developers have experienced occasional test failures like:

 ```
 [INFO] 26 06 2018 09:33:31.658:INFO [karma]: Karma v1.7.1 server started at http://0.0.0.0:9876/
 [INFO] 26 06 2018 09:33:31.662:INFO [launcher]: Launching browser PhantomJS with unlimited concurrency
 [INFO] 26 06 2018 09:33:31.707:INFO [launcher]: Starting browser PhantomJS
 [INFO] 26 06 2018 09:33:41.858:INFO [PhantomJS 2.1.1 (Linux 0.0.0)]: Connected on socket 9qL2Zvu8cceP9O7ZAAAA with id 75060365
 [INFO] 26 06 2018 09:33:52.659:WARN [PhantomJS 2.1.1 (Linux 0.0.0)]: Disconnected (1 times), because no message in 10000 ms.
 [INFO] PhantomJS 2.1.1 (Linux 0.0.0) ERROR
 [INFO]   Disconnected, because no message in 10000 ms.
 [INFO]
 [INFO]
 [ERROR] npm ERR! Test failed.  See above for more details.
 ...
 [ERROR] Failed to execute goal com.github.eirslett:frontend-maven-plugin:1.3:npm (npm test) on project brooklyn-ui-utils: Failed to run task: 'npm test' failed. (error code 1) -> [Help 1]
 [ERROR]
 [ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
 [ERROR] Re-run Maven using the -X switch to enable full debug logging.
 [ERROR]
 [ERROR] For more information about the errors and possible solutions, please read the following articles:
 [ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException
 [ERROR]
 [ERROR] After correcting the problems, you can resume the build with the command
 [ERROR]   mvn <goals> -rf :brooklyn-ui-utils
 ```

 This appears to be a non-deterministic environment issue. The workaround is to run the test again,
 resuming the build from the failed module. For example:

 ```bash
 mvn clean install -rf :brooklyn-ui-utils
 ```


 ### Docker Build Failure on OS X (no such file)

 Developers have experienced build failures on OS X like:

 ```
 [ERROR] npm ERR! path /usr/build/ui-modules/app-inspector/node_modules/d3-dsv/bin/json2dsv
 [ERROR] npm ERR! code ENOENT
 [ERROR] npm ERR! errno -2
 [ERROR] npm ERR! syscall chmod
 [ERROR] npm ERR! enoent ENOENT: no such file or directory, chmod '/usr/build/ui-modules/app-inspector/node_modules/d3-dsv/bin/json2dsv'
 [ERROR] npm ERR! enoent This is related to npm not being able to find a file.
 [ERROR] npm ERR! enoent
 [ERROR]
 [ERROR] npm ERR! A complete log of this run can be found in:
 [ERROR] npm ERR!     /root/.npm/_logs/2018-07-09T17_46_07_187Z-debug.log
 ```

 This is Docker bug: https://github.com/docker/for-mac/issues/2296.

 Try to run the build again from the failed module (but this will not always work). For example:

 ```bash
 pushd ui-modules/app-inspector
 find ./ -type d -name "node_modules" -exec rm -rf {} \+
 popd
 mvn clean install -rf :brooklyn-ui-app-inspector
 ```

 Alternatively, run Docker on a Linux VM (e.g. see instructions at
 https://docs.docker.com/install/linux/docker-ce/centos/#install-docker-ce).

 ```bash
 ###
  # Install Docker
  ##
 sudo yum install -y yum-utils \
   device-mapper-persistent-data \
   lvm2
 sudo yum-config-manager \
     --add-repo \
     https://download.docker.com/linux/centos/docker-ce.repo

 sudo yum install docker-ce

 # Or if you hit https://github.com/docker/for-linux/issues/20#issuecomment-312760808
 #sudo yum install --setopt=obsoletes=0 \
 #    docker-ce-17.03.2.ce-1.el7.centos.x86_64 \
 #    docker-ce-selinux-17.03.2.ce-1.el7.centos.noarch

 sudo systemctl start docker

 ###
  # Download the Brooklyn UI code
  ##
 sudo yum install -y git-core
 git clone https://github.com/apache/brooklyn-ui.git
 cd brooklyn-ui/

 ###
  # Build.
  ##
 docker build -t brooklyn:ui .
 docker run -i --rm --name brooklyn-ui -v ${HOME}/.m2:/root/.m2 -v ${PWD}:/usr/build -w /usr/build brooklyn:ui mvn clean install
 ```

 ### Dockerfile Development

 The Dockerfile should work for you. The notes below are for if you are trying to tweak the
 Dockerfile. The dependencies (e.g. `make`) are to allow yarn to build particular modules
 from source. Without this, it gives an error like:

 ```
 [ERROR]   ⚠ The `/usr/build/ui-modules/home/node_modules/mozjpeg/vendor/cjpeg` binary doesn't seem to work correctly
 [ERROR]   ⚠ mozjpeg pre-build test failed
 [ERROR]   ℹ compiling from source
 [ERROR]   ✖ Error: autoreconf -fiv && ./configure --disable-shared --prefix="/usr/build/ui-modules/home/node_modules/mozjpeg/vendor" --bindir="/usr/build/ui-modules/home/node_modules/mozjpeg/vendor" --libdir="/usr/build/ui-modules/home/node_modules/mozjpeg/vendor" && make --jobs=4 && make install --jobs=4
 [ERROR] Command failed: make --jobs=4
 [ERROR] /bin/sh: 1: make: not found
 ```

 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->
	# [![Brooklyn](https://brooklyn.apache.org/style/img/apache-brooklyn-logo-244px-wide.png)](http://brooklyn.apache.org/)

	### Apache Brooklyn UI Sub-Project

	This repo contains the JavaScript UI for Apache Brooklyn plus server-side code to enable module lookup and discovery.

	Essential contents:

	* `modularity-server`: Java OSGi modules to facilitate registering and discovering available modules
	* `ui-modules`: Individual Angular JS modules -- each can be run as a standalone Node app,
	or built as OSGi bundle including the WAR to be served collectively by an OSGi server
	(each using the modularity server-side endpoints to find available modules and allow navigation between them,
	and the `home` module providing a convenient entry point)
	* `features`: Build an OSGi feature


	### Building the project

	Two methods are available to build this project: within a docker container or directly with maven.

	#### Using docker

	The project comes with a `Dockerfile` that contains everything you need to build this project.
	First, build the docker image:

	```bash
	docker build -t brooklyn:ui .
	```

	Then run the build:

	```bash
	docker run -i --rm --name brooklyn-ui -v ${HOME}/.m2:/root/.m2 -v ${PWD}:/usr/build -w /usr/build brooklyn:ui mvn clean install
	```

	### Using maven

	You will need the following binaries installed first:
	* `java`
	* `maven` (please note, you will need version 3.5.2 or later)
	* `git`
	* `bzip2`
	* `libpng`. This has different package names based on the distribution:
	* `libpng-devel` for CentOS
	* `libpng-dev` for Debian/Ubuntu (also requires `libpng12`)
	* `libpng` for MacOS

	_Optional, if the `libpng` cannot be found when building (package names may vary; often these are not required):_
	* `libpng` (or `libpng-devel` on CentOS, `libpng-dev` on Debian/Ubuntu, `libpng12` sometimes)
	* _`automake (opt)`_
	* _`autoconf`_
	* _`libtool`_
	* _`dpkg`_
	* _`pkgconfig`_
	* _`nasm`_
	* _`gcc`_
	* _`build-essential`_
	* `bzip2`
	* _`pngquant`_
	* _`libfontconfig1-dev`_

	With this, simply run:

	```bash
	mvn clean install
	```


	## Dev

	Instructions for developing UI modules is included in subdirectories, but in short all you need to do once things are configured
	is to run `make` in the relevant module directory, with a Brooklyn REST server on 8081.


	## Documentation

	For developers, the following links may be useful:

	* [Overview and architecture of the project](docs/overview.md)
	* [Building individual module / Dev environment](ui-modules/README.md)
	* [Skinning the UI with custom themes](docs/skinning.md)
	* [Customizing and embedding the UI](docs/customizations.md)


	## Troubleshooting

	### Build Failure (Cached Dependencies)

	The first time `mvn clean install` or `yarn run build` is run, it will cache dependencies in `node_modules`.
	If a dependency is subsequently upgraded, this could cause an incompatibility. For example, it can cause
	a test failure such as:

	20 06 2018 17:28:41.143:ERROR [karma]: { Error: spawn ENOTDIR
	at ChildProcess.spawn (internal/child_process.js:357:11)
	at spawn (child_process.js:528:9)
	at spawnWithoutOutput (/Users/aledsage/repos/apache/brooklyn/brooklyn-ui/ui-modules/utils/node_modules/karma/lib/launchers/process.js:141:24)

	The fix is to delete the auto-generated `node_modules` directories:

	```bash
	cd /path/to/brooklyn_ui
	find ./ -type d -name "node_modules" -exec rm -rf {} \+
	```

	### Errors with libpng

	On many systems the `imagemin` dependency of JS shows errors during install, often due to `libpng` missing
	or the `jpeg` compilation failing (note this one can be a non-fatal error at the time, but the build will then fail).

	Consult the list above of dependencies to install, and make sure you wipe the `node_modules` dirs.

	If libpng still seems to be missing and you are using an M1 Mac then the following lines may help.

	```bash
	arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
	arch -x86_64 /usr/local/bin/brew install libpng
	```

	This installs th x86 version of brew and uses that to install the x86 version of the libpng library. This won't affect your arm64 brew or anything installed using it.

	If it still fails, try installing `nvm` (curl-to-bash) then `nvm ls-remote` and `nvm install v12.9.0` (or other latest).
	Then retry the `mvn` build; even though `mvn` uses a different version of `node` and `yarn`, simply installing the latest
	node version sometimes sorts out errors.


	### Docker Build Failure (Dependencies for Wrong Architecture)

	When the build is run locally, it will download executables such as `phantomjs`, for the
	local architecture. If the build is subsequently run in a Docker container, mounting the
	local repo directory, it may be incompatible. An example error is:

	```
	[INFO] 25 06 2018 15:26:48.224:ERROR [launcher]: PhantomJS stdout:
	[INFO] 25 06 2018 15:26:48.224:ERROR [launcher]: PhantomJS stderr: /usr/build/ui-modules/utils/node_modules/phantomjs-prebuilt/lib/phantom/bin/phantomjs: 1: /usr/build/ui-modules/utils/node_modules/phantomjs-prebuilt/lib/phantom/bin/phantomjs: Syntax error: Unterminated quoted string
	```

	You can check the file type by running:

	```bash
	file ./ui-modules/utils/node_modules/phantomjs-prebuilt/lib/phantom/bin/phantomjs

	./ui-modules/ui-utils/node_modules/phantomjs-prebuilt/lib/phantom/bin/phantomjs: Mach-O 64-bit executable x86_64
	```

	The fix is to delete the auto-generated `node_modules` directories:

	```bash
	cd /path/to/brooklyn_ui
	find ./ -type d -name "node_modules" -exec rm -rf {} \+
	```

	### Test Failure (PhantomJS)

	Developers have experienced occasional test failures like:

	```
	[INFO] 26 06 2018 09:33:31.658:INFO [karma]: Karma v1.7.1 server started at http://0.0.0.0:9876/
	[INFO] 26 06 2018 09:33:31.662:INFO [launcher]: Launching browser PhantomJS with unlimited concurrency
	[INFO] 26 06 2018 09:33:31.707:INFO [launcher]: Starting browser PhantomJS
	[INFO] 26 06 2018 09:33:41.858:INFO [PhantomJS 2.1.1 (Linux 0.0.0)]: Connected on socket 9qL2Zvu8cceP9O7ZAAAA with id 75060365
	[INFO] 26 06 2018 09:33:52.659:WARN [PhantomJS 2.1.1 (Linux 0.0.0)]: Disconnected (1 times), because no message in 10000 ms.
	[INFO] PhantomJS 2.1.1 (Linux 0.0.0) ERROR
	[INFO] Disconnected, because no message in 10000 ms.
	[INFO]
	[INFO]
	[ERROR] npm ERR! Test failed. See above for more details.
	...
	[ERROR] Failed to execute goal com.github.eirslett:frontend-maven-plugin:1.3:npm (npm test) on project brooklyn-ui-utils: Failed to run task: 'npm test' failed. (error code 1) -> [Help 1]
	[ERROR]
	[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
	[ERROR] Re-run Maven using the -X switch to enable full debug logging.
	[ERROR]
	[ERROR] For more information about the errors and possible solutions, please read the following articles:
	[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException
	[ERROR]
	[ERROR] After correcting the problems, you can resume the build with the command
	[ERROR] mvn <goals> -rf :brooklyn-ui-utils
	```

	This appears to be a non-deterministic environment issue. The workaround is to run the test again,
	resuming the build from the failed module. For example:

	```bash
	mvn clean install -rf :brooklyn-ui-utils
	```


	### Docker Build Failure on OS X (no such file)

	Developers have experienced build failures on OS X like:

	```
	[ERROR] npm ERR! path /usr/build/ui-modules/app-inspector/node_modules/d3-dsv/bin/json2dsv
	[ERROR] npm ERR! code ENOENT
	[ERROR] npm ERR! errno -2
	[ERROR] npm ERR! syscall chmod
	[ERROR] npm ERR! enoent ENOENT: no such file or directory, chmod '/usr/build/ui-modules/app-inspector/node_modules/d3-dsv/bin/json2dsv'
	[ERROR] npm ERR! enoent This is related to npm not being able to find a file.
	[ERROR] npm ERR! enoent
	[ERROR]
	[ERROR] npm ERR! A complete log of this run can be found in:
	[ERROR] npm ERR! /root/.npm/_logs/2018-07-09T17_46_07_187Z-debug.log
	```

	This is Docker bug: https://github.com/docker/for-mac/issues/2296.

	Try to run the build again from the failed module (but this will not always work). For example:

	```bash
	pushd ui-modules/app-inspector
	find ./ -type d -name "node_modules" -exec rm -rf {} \+
	popd
	mvn clean install -rf :brooklyn-ui-app-inspector
	```

	Alternatively, run Docker on a Linux VM (e.g. see instructions at
	https://docs.docker.com/install/linux/docker-ce/centos/#install-docker-ce).

	```bash
	###
	# Install Docker
	##
	sudo yum install -y yum-utils \
	device-mapper-persistent-data \
	lvm2
	sudo yum-config-manager \
	--add-repo \
	https://download.docker.com/linux/centos/docker-ce.repo

	sudo yum install docker-ce

	# Or if you hit https://github.com/docker/for-linux/issues/20#issuecomment-312760808
	#sudo yum install --setopt=obsoletes=0 \
	# docker-ce-17.03.2.ce-1.el7.centos.x86_64 \
	# docker-ce-selinux-17.03.2.ce-1.el7.centos.noarch

	sudo systemctl start docker

	###
	# Download the Brooklyn UI code
	##
	sudo yum install -y git-core
	git clone https://github.com/apache/brooklyn-ui.git
	cd brooklyn-ui/

	###
	# Build.
	##
	docker build -t brooklyn:ui .
	docker run -i --rm --name brooklyn-ui -v ${HOME}/.m2:/root/.m2 -v ${PWD}:/usr/build -w /usr/build brooklyn:ui mvn clean install
	```

	### Dockerfile Development

	The Dockerfile should work for you. The notes below are for if you are trying to tweak the
	Dockerfile. The dependencies (e.g. `make`) are to allow yarn to build particular modules
	from source. Without this, it gives an error like:

	```
	[ERROR] ⚠ The `/usr/build/ui-modules/home/node_modules/mozjpeg/vendor/cjpeg` binary doesn't seem to work correctly
	[ERROR] ⚠ mozjpeg pre-build test failed
	[ERROR] ℹ compiling from source
	[ERROR] ✖ Error: autoreconf -fiv && ./configure --disable-shared --prefix="/usr/build/ui-modules/home/node_modules/mozjpeg/vendor" --bindir="/usr/build/ui-modules/home/node_modules/mozjpeg/vendor" --libdir="/usr/build/ui-modules/home/node_modules/mozjpeg/vendor" && make --jobs=4 && make install --jobs=4
	[ERROR] Command failed: make --jobs=4
	[ERROR] /bin/sh: 1: make: not found
	```

	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->