rtyler
/
blueocean-plugin
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

big cleanup of dev docs (#203) 

* big cleanup of dev docs

* fixes for README
This commit is contained in:
Michael Neale 2016-05-26 13:51:46 +10:00
parent afe2211f9f
commit 4e4133cee7
5 changed files with 119 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
README.md
View File

@ -1,41 +1,41 @@
This is the BlueOcean repo. It is a multi-module maven project. Each sub-directory at the root of the repo is jenkins extension.
Blue Ocean is the next generation user experience for Jenkins.
It is a multi-module maven project with a few Jenkins plugins.
Read it:
https://jenkins.io//blog/2016/05/26/introducing-blue-ocean/
Blue Ocean is the new UI project for Jenkins.
![Pirate logo, because it's ocean and stuff](logo-yarrr.png)
Yarr...
# Modules of note
(check the readme in each of them!)
## blueocean-web
BlueOcean Web module, core web module with layout and extention points. You probably want to look at the README for this for how to play with it. This should mostly be infrastructure and core components.
## blueocean-dashboard
BlueOcean Dashboard plugin. Currently contains the bulk of the Blue Ocean user interface.
## blueocean-commons
Common libraries for various modules
## blueocean-rest
Utilities and interfaces for the HTTP api that the Blue Ocean front end needs.
Blue Ocean Dashboard plugin. Currently contains the bulk of the Blue Ocean user interface. This is mostly client side JavaScript built with ES6 and React.
## blueocean-plugin
This plugin currently fulfills two purposes (and so is likely to be separated out into two plugins - TBD):
This plugin currently exists for two purposes (and so is likely to be separated out into two plugins - TBD):
1. Provides the default implementation of the REST Api defined in the `blueocean-rest` plugin.
1. Acts as an aggregator plugin, making it an easy place from which to run Blue Ocean via `hpi:run`.
2. Acts as an aggregator plugin, making it an easy place from which to run Blue Ocean via `hpi:run`.
__NOTE__: As already stated, this plugin is likely to be refactored in the near future.
## blueocean-rest
Java interfaces and classes that specify the definition of the REST API. See the README within this module for more information.
## blueocean-web
Web infrastructure that glues Jenkins and Blue Ocean plugin together on the /blue endpoint.
# Building
# Building and running
## Build everything (from root directory)
Builds all maven modules (run this the first time you check things out, at least)
@ -44,9 +44,35 @@ Builds all maven modules (run this the first time you check things out, at least
$ mvn clean install
```
# Running Blue Ocean
## Running Blue Ocean
```
$ cd blueocean-plugin
$ mvn hpi:run
```
Then open http://localhost:8080/jenkins/blue to start using Blue Ocean.
The Jenkins Classic UI exists side-by-side at its usual place at http://localhost:8080/jenkins.
# Developing
Follow the steps above for getting it running first.
Look in following README's for:
* ``blueocean-dashboard`` guide on how to modify the GUI in the dashboard plugin. https://github.com/cloudbees/blueocean-sample-pipeline-result-ext-plugin has a video/sample of a plugin that extends Blue Ocean.
* ``blueocean-rest`` for how to navigate the rest api.
* ``blueocean-plugin`` for more details on how to actively develop this plugin for both the frontend and backend codebases.
### Tools needed
*Maven* is used for most building. The project is configured to grab all the tools you need from the JavaScript ecosystem to get started.
If you are working on the Javascript, you will need node and gulp installed.
__NOTE__: look in the README.md of the respective modules for more detailed dev docs.
Go into blueocean-web and follow the README.md!
# Debug and live reload with IntelliJ
@ -61,3 +87,13 @@ Automatically deploys changes to an instance of blueocean that is run with hpi:r
* Runner > Properties: Enable Skip tests
* Runner > VM Options: `-Dblueocean.config.file=../app.properties`
3. Debug new configuration, and after compilation the class file will be reloaded
# Help
Need help?
You can chat to folks on #jenkins-ux on freenode (IRC). You can also email the jenkins-dev email list (google group: https://groups.google.com/forum/#!forum/jenkinsci-dev) - but ensure you use the prefix [Blue Ocean] in your subject line when posting.
# Presentations
Advanced front end development with react, redux and stuff by @scherler: https://docs.google.com/presentation/d/1dbaYTIGjGT9xX1JnWnaqjMumq94M9nGwljfMQaVtUFc/edit?usp=sharing

5
blueocean-dashboard/README.md
View File

@ -1,12 +1,13 @@
# Dashboard plugin
This plugin provides the main Dashboard user interface for Blue Ocean.
It has a bunch of GUI components and extension points for other plugins to extend.
This is where the fun happens.
## Running this
## Running and modifying this plugin
### With mvn
1. Go into `blueocean-plugin` and run `mvn hpi:run` in a terminal. (mvn clean install from the root of the project is always a good idea regularly!)
2. From this directory, run `gulp bundle:watch` to watch for JS changes and reload them.
3. Open browser to http://localhost:8080/jenkins/blue/ to see this

44
blueocean-plugin/README.md
View File

@ -2,12 +2,13 @@
This plugin allows blueocean to run as a plugin inside an existing Jenkins.
## Usage during development
## To start it all up
To use this in development:
To use this in development or to tyre kick:
`mvn hpi:run`
(make sure you have run `mvn clean install` from the parent first)
Blue Ocean UI:
@ -19,5 +20,40 @@ Embedded Jenkins UI (so you can create some pipelines for fun):
This links source from the other modules. So if you make a source change to rest, web or other modules,
it will be applied here. If its a UI module, you will need to run `gulp rebundle` in the UI modules directory
to watch for JS/HTML changes and live reload them.
it will be applied here. If its a UI module, you will need to have gulp installed (http://gulpjs.com/) and run `gulp bundle:watch` in the modules directory that has the JS you want to watch for changes and to have the reloaded live.
# Running Blue Ocean in development
If you want to add to some extension points or mess with the GUI as it is right now, take a look at the `blueocean-dashboard` module (actually a plugin). Also take a look at: https://github.com/cloudbees/blueocean-sample-pipeline-result-ext-plugin for an example of an plugin that augments Blue Ocean.
Run in this directory:
`mvn hpi:run`
## Verify it's working
curl -v -X GET http://localhost:8080/jenkins/blue/rest/organizations/jenkins/
Should print:
{"name":"jenkins"}
Why not also try: `curl http://localhost:8080/jenkins/blue/rest/organizations/jenkins/pipelines/`
Load it in browser to see your ui code:
http://localhost:8080/jenkins/blue
Load it in the browser to see the embedded Jenkins:
http://localhost:8080/jenkins
Look in blueocean-dashboard plugin for instructions on how to make changes to GUI code.

12
blueocean-rest/README.md
View File

@ -1,20 +1,24 @@
# REST api for Blue Ocean components
This defines the http/REST like interface that Blue Ocean components use.
# Usage
## Crumbs
Jenkins usually requires a "crumb" with posted reuqests to prevent request forgery and other shenanigans.
Jenkins usually requires a "crumb" with posted requests to prevent request forgery and other shenanigans.
To avoid needing a crumb to POST data, the header `Content-Type: application/json` *must* be used.
## Run BlueOcean plugin
## Run Blue Ocean plugin
cd bluecoean-plugin
mvn hpi:run
This will launch jenkins with BlueOcean plugin.
This will launch a development Jenkins instance with the Blue Ocean plugin and this plugin ready to go.
BlueOcean UI is available at:
http://localhost:8080/jenkins/bo
http://localhost:8080/jenkins/blue
BlueOcean rest API base URL is:

59
blueocean-web/README.md
View File

@ -1,60 +1,21 @@
# UI Plugin
# Web middleware
This module mostly contains middleware for serving up "/blue" GUI.
In general, you shouldn't need to modify stuff in for plugins or features as it is infrastructure. Move along.
This is the main UI guts of blueocean. Javascript magic happens here as well as some core web classes.
Look for blueocean.js for excitement.
# Running Blue Ocean in development
## how this works with Javascript
If you want to add to some extension points, take a look at the `blueocean-dashboard` module (actually a plugin) for an example.
Jenkins-js-modules and friends are used to power this. Look in `src/main/js` in any plugin.
## Firstly build all modules from root
If you wish to make changes to blueocean.js in this plugin, then you will need to install gulp (http://gulpjs.com/), and then run `cd blueocean-plugin && mvn hpi:run` in a separate terminal.
cd ..
mvn clean install
## Run it in plugin dev mode
Then run:
To hack on blue ocean UI, you will want to run it embedded in a Jenkins you can add jobs to and so on.
To do this, use the `blueocean-plugin` module:
cd blueocean-plugin
mvn hpi:run
## Verify it's working
curl -v -X GET http://localhost:8080/jenkins/blue/rest/organizations/jenkins/
Should print:
{"name":"jenkins"}
Why not also try: `curl http://localhost:8080/jenkins/blue/rest/organizations/jenkins/pipelines/`
Load it in browser to see your ui code:
http://localhost:8080/jenkins/blue
Load it in the browser to see the embedded Jenkins:
http://localhost:8080/jenkins
## Javascript and HTML development
Jenkins-js-modules and friends are used to power this. Look in `src/main/js`.
If you wish to make changes to blueocean.js, then you will need to install gulp (http://gulpjs.com/), and then run (in a separate terminal to mvn hpi:run):
```
$ cd blueocean-web
```
$ gulp bundle:watch
```
(or run gulp, after each change) in the `blueocean-web` directory. This will pick up any changes.
(or run gulp, after each change) in this directory. This will pick up any changes.
If you are editing any other UI modules, run the same in their respective directories.