dev-doc: Tutorial on modifying web UI
Walk through the process of customizing the web UI with a
new logo on the login and screen and header bar
Change-Id: I1acba8765190fe0ef633c5203cd5c77260e56829
Signed-off-by: Andrew Geissler <geissonator@yahoo.com>
diff --git a/development/web-ui.md b/development/web-ui.md
new file mode 100644
index 0000000..a5432c1
--- /dev/null
+++ b/development/web-ui.md
@@ -0,0 +1,110 @@
+# OpenBMC Web User Interface Development
+
+**Document Purpose:** How to customize, build, and run the OpenBMC Web UI
+
+**Audience:** Programmer familiar with HTML and AngularJS
+
+**Prerequisites:** Current Linux, Mac, or Windows system
+
+### Overview
+
+The [phosphor-webui](https://github.com/openbmc/phosphor-webui) repository
+provides a web-based interface for an OpenBMC. The phosphor-webui uses the
+AngularJS framework to interact with the BMC via REST API calls. It allows users
+to view hardware information, update firmware, set network settings, and much
+more.
+
+A common use case for changes to the web UI is to put some system specific
+branding into it. This lesson will focus on how to do that.
+
+### Load web UI against QEMU
+
+1. Connect to web UI in QEMU
+
+ You will need the QEMU session running per instructions in section
+ "Download and Start QEMU Session" of [dev-environment](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
+
+ Assuming you used the default of 2443 for the https port in your QEMU
+ session, you will point your web browser to https://localhost:2443.
+ Login with default userid and password and verify basic web UI features are
+ working as expected.
+
+ **Note** You will need to approve the security exception in your browser to
+ connect. OpenBMC is running with a self-signed SSL certificate. Accepting
+ this is key for the next steps.
+
+### Customize web UI code
+
+1. Clone the repository
+
+ ```
+ git clone https://github.com/openbmc/phosphor-webui.git
+ ```
+
+2. Install appropriate packages and start web UI
+
+ Follow the directions in the phosphor-webui [README](https://github.com/openbmc/phosphor-webui/blob/master/README.md)
+ to install the required packages and start the web UI. You can use the
+ development environment created in [dev-environment](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
+ or your own system assuming you install the required packages noted in the
+ README.
+
+3. Customize the web UI login screen and verify
+
+ Kill your npm run from the previous step using Ctrl^C. Grab a png that you
+ will use to represent your customized version of OpenBMC. Feel free to use
+ any .png you wish for this step.
+ ```
+ wget http://www.pngmart.com/files/3/Free-PNG-Transparent-Image.png
+ ```
+
+ Copy your new .png into the appropriate directory
+ ```
+ cp Free-PNG-Transparent-Image.png app/assets/images/
+ ```
+
+ Point to that new image in the web UI HTML
+ ```
+ vi app/login/controllers/login-controller.html
+ # Replace the logo.svg near the top with Free-PNG-Transparent-Image.png
+ <img src="../../assets/images/Free-PNG-Transparent-Image.png" class="login__logo" alt="OpenBMC logo" role="img"/>
+ ```
+
+ Start up the server with your change
+ ```
+ npm run-script server
+ ```
+
+ Load web browser at https://localhost:8080 and verify your new image is on
+ the login screen.
+
+ Kill your npm run using Ctrl^C.
+
+4. Customize the header with the new image and verify
+
+ The header is on every page in the web UI. It has a smaller version of the
+ logo in it which we are changing with this step.
+
+ Similar to the previous step, modify the appropriate HTML for the header:
+ ```
+ vi app/common/directives/app-header.html
+ # Replace logo.svg with Free-PNG-Transparent-Image.png again
+ <div class="logo__wrapper"><img src="../../assets/images/Free-PNG-Transparent-Image.png" class="header__logo" alt="company logo"/></div>
+ ```
+
+ Start up the server with your change
+ ```
+ npm run-script server
+ ```
+ Browse to https://localhost:8080 and verify your new image is on the header.
+ Note that you will need to log in to view the header. Point the web UI to your
+ QEMU session by typing the QEMU session (e.g. localhost:2443) in the "BMC HOST
+ OR BMC IP ADDRESS" field.
+
+Note that in the HTML where you're replacing the images, there is also the
+corresponding text that goes with the images. Changing the text to match
+with your logo is also something you can easily do to customize your creation
+of an OpenBMC system.
+
+And that's it! You've downloaded, customized, and run the OpenBMC phosphor-webui
+code!