~bac/juju-gui/trunkcopy

Viewing changes to README

Committer: Nicola Larosa
Date: 2012-12-12 10:08:50 UTC
mfrom: (274.1.6 1086512-revise-docs)
Revision ID: nicola.larosa@canonical.com-20121212100850-c689dexsczxzdm3p

Put deploy docs in README, add HACKING.

Move the development instructions from the README file to a newly created HACKING one, update them, link the HACKING into the docs. Put deploying instructions in the README file. Revise all docs updating them, and fixing markup and links.

R=frankban, gary.poster
CC=
https://codereview.appspot.com/6924047

files added:
HACKING

docs/hacking.rst

files modified:
Makefile

README

docs/architecture.rst

docs/d3-component-framework.rst

docs/index.rst

docs/process.rst

docs/style-guide.rst

Show diffs side-by-side

added added

removed removed

README

======

README

======

Developer Install

=================

Juju GUI uses nodejs based development tools.

You'll need nodejs & npm from the ppa::

$ sudo add-apt-repository ppa:chris-lea/node.js

$ sudo apt-get update

$ sudo apt-get install nodejs npm

You also need ImageMagick::

$ sudo apt-get install imagemagick

The linter will be installed locally per branch, but if you want editor

integration, you may want to install jshint globally in your system::

$ sudo npm install -g jshint

For building the docs, you also need sphinx::

$ sudo apt-get install python-sphinx

To make releases, you'll need pytz::

$ sudo apt-get install python-tz

The gui frontend can be installed with::

$ bzr branch lp:juju-ui trunk

$ cd trunk

$ make server

It may take a while for the server to start the first time as npm will

need to download packages. When ready, the server will print:

Server listening on 8888

You can then access the GUI at http://localhost:8888

You'll also need to deploy a juju environment with REST api access.

Currently that work resides in a pipeline of juju branches. The

recommended branch to use as a server is ``lp:~hazmat/juju/rapi-delta``.

You can use it with any environment, but for dev purposes, a local

environment works well. One environment option specific to this branch

is the api-port. An appropriate sample configuration::

default: dev

environments:

dev:

type: local

data-dir: /home/kapil/.juju/local

admin-secret: b3a5dee4fb8c4fc9a4db04751e5936f4

default-series: precise

juju-origin: ppa

api-port: 8081

Note that juju-origin is set to the ppa, the api server runs outside of

the container, and is launched using whichever branch you're using.

Also note that the api-port should be set at 8081, which the gui's

initial environment connection currently defaults to.

You'll need to bootstrap the local environment, and deploy one service.

The api server needs access to the provisioning credentials which are

lazily initialized in juju upon usage.

Juju-gui and rapi-delta can communicate via an encrypted WebSockets

connection: to enable it, add the following line to the config above::

api-secure: true

You will also need to edit your ``app/config.js`` replacing

``ws://localhost:8081/ws`` with ``wss://localhost:8081/ws``.

By default, rapi-delta uses a self-signed certificate; because of that you

will need to visit the https://localhost:8081/ws WebSockets URL with your

browser and accept the included self-signed certificate, or the WebSockets

encrypted connection will not work.

In order to use a different certificate, you add an api-keys option to the

config above: its value will be the path of the directory containing the

certificate and the private key, whose filenames will have to be respectively

``juju.crt`` and ``juju.key``.

After which, the gui should be functional (it automatically polls the

api server for establishing a websocket).

Running unit tests

==================

$ xdg-open test/index.html

100

Documentation

101

=============

102

103

Generated JavaScript documentation is available in the yuidoc directory.

104

Start with the index.html file. You can view the docs by running::

105

106

$ xdg-open yuidoc/index.html

107

108

To regenerate the docs run::

109

110

$ make yuidoc

111

112

The documentation for YUIDoc markup is at

113

http://yui.github.com/yuidoc/syntax/ .

114

115

Running lint

116

============

117

118

$ jshint --config=jshint.config `bzr ls -RV -k file | grep -v assets/`

119

120

Making releases

121

===============

122

123

To make a release, you must either be in a checkout of lp:juju-gui

124

without uncommitted changes, or you must override one of the

125

`pertinent variable names`_ to force a release.

126

127

.. _`pertinent variable names`: `Potentially Useful Release-Oriented Makefile Variables`_

128

129

You also need to have a gpg key, and the python-pytz package installed (as

130

well as launchpadlib, but that is installed by default in Ubuntu).

131

132

See the Process document (docs/process.rst) for step-by-step checklists to

133

make developer and stable releases.

134

135

Potentially Useful Release-Oriented Makefile Variables

136

------------------------------------------------------

137

138

The following is a list of pertinent Makefile variables.

139

140

FINAL

141

Set FINAL to any non-empty value to make a final release. This will cause

142

the bzr revno to be omitted from the tarball name, and (if you use the

143

release target) will cause the release to be uploaded to the stable series

144

rather than the trunk series. Example usage::

145

146

$ FINAL=1 make release

147

148

PROD

149

By default, releases will be uploaded to staging.launchpad.net, which is a

150

separate version of Launchpad that uses a temporary database. This can be

151

convenient for trying out the release process in the Makefile without

152

affecting our actual production releases. Set PROD to any non-empty value

153

to send uploads to launchpad.net, the production version of Launchpad, when

154

you are ready to make a real release.

155

156

Note that you may need to ask the webops to turn off the two-factor

157

authentication on your Launchpad staging account in order for the staging to

158

work. Go to the #launchpad-ops channel on the Canonical IRC server and ask

159

something like "webops, could you disable 2FA on my staging account?"

160

161

Example usage::

162

163

$ PROD=1 make release

164

165

IS_TRUNK_CHECKOUT

166

Set this to any non-empty value to force the Makefile to believe it is

167

working with a trunk checkout. Example usage::

168

169

$ IS_TRUNK_CHECKOUT=1 make release

170

171

HAS_NO_CHANGES

172

Set this to any non-empty value to force the Makefile to believe that the

173

current code tree has no changes. Example usage::

174

175

$ HAS_NO_CHANGES=1 make release

176

177

IS_SAFE_RELEASE

178

Set this to any non-empty value to force the Makefile to bypass checks of

179

IS_TRUNK_CHECKOUT and HAS_NO_CHANGES. Example usage::

180

181

$ IS_SAFE_RELEASE=1 make release

182

183