chrome/common/extensions/docs/server2/README

   1 --------
   2 Overview
   3
   4 This is a Google App Engine server which serves the documentation for Chrome
   5 apps and extensions. At time of this writing, the primary URL is:
   6 http://developer.chrome.com/.
   7
   8
   9 ---------------------
  10 Developing the Server
  11
  12 You shouldn't need app engine locally to develop the server, preview.py should
  13 be sufficient. If for some reason you want to test against the app engine SDK:
  14
  15   1. Download the python Google App Engine SDK from:
  16      https://developers.google.com/appengine/downloads
  17
  18   2. Run './start_dev_server.py <path/to/dev_appserver.py>'
  19      (dev_appserver.py is part of the App Engine)
  20
  21   3. View docs at http://localhost:8080/(apps|extensions)/<doc_name>
  22
  23 NOTE: The dev server will not work right way: you need to populate its
  24 Datastore. You will need a local datastore cache in the working directory where
  25 you started the dev server, and you will need to manually instruct the dev
  26 server to pull data from that file:
  27
  28   1. Run './update_cache.py --no-push --save-file=FOOCACHE'. This will take
  29      a very long time (30-40 minutes). It is advisable that you keep a copy
  30      of this file around if you plan use the dev server often. It can be
  31      updated much faster (< 3 minutes) in that case by also including
  32      --load-file=FOOCACHE on subsequent update_cache.py runs.
  33
  34      You MUST have branch heads fetched in your local repo in order for your
  35      local data set to be populated correctly. You can accomplish this by
  36      running:
  37
  38        gclient sync --with_branch_heads
  39        git fetch origin
  40
  41      You may also specify --commit=<commitish> when running update_cache.py in
  42      order to update the cache from a specific commit. This may be a commit ID,
  43      or a partial commit ID, or a local branch ref, etc. To test local changes,
  44      you MUST commit them locally and use the local commit to update your cache.
  45
  46   2. Once you have a cache (e.g. FOOCACHE) in the working directory of your
  47      dev server, visit the URL:
  48
  49        http://localhost:8080/_update_cache/FOOCACHE
  50
  51      The server should take about a minute to fully populate its Datastore
  52      from the data in your FOOCACHE file. Now you have a working dev server!
  53
  54
  55 ------------------------------------------------------------
  56 Using Google Cloud Storage content providers with preview.py
  57
  58   1. create a directory "[...]/server2/local_debug/gcs/<bucketname>" for every
  59      gcs bucket referenced in content_providers.json
  60
  61   2. copy files to the respective local bucket directories. Preview.py has
  62      no access to the real Google Cloud Storage.
  63
  64
  65 --------------------
  66 Deploying the Server
  67
  68 You will need to have access to the http://chrome-apps-doc.appspot.com app.
  69 Contact kalman@chromium.org or rockot@chromium.org to obtain access.
  70
  71 Once you have access:
  72
  73 1. Increment the version in app.yaml so we can roll back if the update breaks.
  74
  75 2. Run build_server.py. This copies some depenencies from /third_party into the
  76    server directory so that they get uploaded to App Engine.
  77
  78 3. Run appcfg.py (supplied with the App Engine SDK) to upload the server code:
  79
  80     appcfg.py update .
  81
  82 4. When prompted for your credentials, enter the information for the account
  83    that has access to the production app.
  84
  85 5. Go to http://www.appspot.com, select the docs project, click "versions" in
  86    the sidebar, and make the version you just deployed the "default" version.
  87
  88    If you get an error about too many versions when deploying, go into this
  89    view and delete the version which was deployed the longest time ago.  Then
  90    try to deploy again.
  91
  92
  93 ----------------------
  94 Updating the Datastore
  95
  96 Even when the server code hasn't changed, new data is constantly flowing into
  97 the chromium repo and some of that data includes changes to new or existing
  98 content hosted by the server. In order for the front-end to reflect these
  99 changes, new data must be pushed into the project's Datastore.
 100
 101 This is done periodically by a Compute Engine instance running the
 102 update_cache.py tool. While it is possible to push from other hosts if you
 103 get all the right credentials in all the right places, it is strongly
 104 discouraged and also therefore not documented.
 105
 106 To force a push safely from the VM, navigate to the developer console under
 107 Compute -> Compute Engine -> VM instances and open SSH for the "git-processor"
 108 instance. From within the SSH session, first switch to user "git-processor":
 109
 110   sudo su - git-processor
 111
 112 You can run './update-docs.sh' from the home directory there. This will
 113 automatically fetch any new objects from the upstream repository and then
 114 perform a full update if there are pending changes.
 115
 116 It's almost never necessary to use this tool. For one interesting example,
 117 consider the case where no new commits are landing in the chrome repository
 118 but a change was just pushed to one of the GCS providers (like say, the
 119 chromedocs-multidevice bucker). In this case, you may want to force an update
 120 of only the content_providers data.
 121
 122   ./update_docs.sh --data-source=content_providers --force
 123
 124 This will safely do the push for you, ensuring that the automated job
 125 does not collide with your own.
 126