• Update Ansible playbooks to setup 1 Cloud Load Balancer + 2 Cloud Servers in ORD and DFW each.
• Get SSL certificate from Jesse and install it on load balancers.

The HTML for the Getting Started Guides is generated under docs/_build/. This is generated by Sphinx and needs to be styled to match the rest of the new developer.rackspace.com.

/sdks/java/index.html

The new developer web site will have a community page with a sponsorship form on it. Since this is a static site generated by Jekyll, we need to figure out how we could process the sponsorship form's submission.

Assume that the form will contain a file upload field, amongst other input fields. Also assume, for the initial release, that the contents of the form can be emailed to our Outreach mailing list.

Some possibilities to consider:

1. Should we throw a simple script on the server to process the form and redirect back to a static page?
2. Should we use an external service like http://getsimpleform.com/ for processing the form?

I've spoken with Anne Gentle and she has informed me that the current API reference source lives in https://github.com/rackerlabs/docs-api-reference. She is on board with moving this source from that repo into this one (https://github.com/rackerlabs/developer.rackspace.com), under a directory (say api_ref) that will be a sibling of the site_source and docs directories.

Before and after doing this move, please let Anne Gentle and Diane Fleming know. After the move is done, one of them needs to delete the old repo to prevent accidental commits to it.

Since we're using doctype html (HTML5), could we change <div class="header"> and <div class="footer"> to <header> and <footer>?

/sdks/python/index.html

All of these need to be run as sudo; Should be baked into ansible playbook for Vagrant dev box.

• apt-get update
• apt-get install build-essential
• apt-get install ruby-odbc (don't know why, but ruby1.9 wont install without it)
• apt-get install ruby1.9
• gem install jeykll
• gem install execjs
• gem install stringex
• apt-get install nodejs
• cd /vagrant_data
• jekyll build --source ./ --destination /var/www/html/developer.rackspace.com/

The Python samples for Cloud Images are currently inconsistent with the samples from other languages and services:

• Each sample is a complete program, including imports and so on.
• Samples are quite long, comparatively.
• Samples read and write from stdin and stdout.

This issue requires HTML/CSS/images derived from the SDKs page mock up. I have requested these assets from our designer, Patrick Deuley. Until we have these assets, I'm moving this issue out of the sprint and into the backlog.

Depends on #74

Should NOT be done until we are ready to switch the site over from the current one to the new one.

Create an /etc/motd file that has enough information for an external operator to understand the deployment and be able to find deployment info; for example, it should have a link to our deployment runbook and howto checklist.

• Below the row of 3 horizontal boxes, replace the static "Developer Discount", "Openstack Support" and "Devops Blog" excerpts with 3 actualy blog post excerpts. See the code here on how to generate these 3 excerpts: https://github.com/rackerlabs/developer.rackspace.com/blob/master/site_source/_includes/looking_for_more.html

/sdks/ruby/index.html

See this line: https://github.com/rackerlabs/developer.rackspace.com/blob/master/deploy/roles/jekyll/tasks/main.yml#L26. It has a reference to vagrant_data. This file belongs to the jekyll role which is part of the dev_web.yml and prod_jenkins.yml playbooks (since we need to install jekyll in development and on Jenkins).

The vagrant_data assumption works when provisioning a development environment but not when provisioning a Jenkins environment. In other words, while the dev_web.yml playbook succeeds, the prod_jenkins.yml playbook fails with this error:

$ ansible-playbook prod_jenkins.yml -i inventory/prod/
...
TASK: [jekyll | Install Jekyll and its dependencies] ************************** 
failed: [jenkins_master_1] => {"changed": true, "cmd": ["bundle", "install", "--gemfile=/vagrant_data/Gemfile"], "delta": "0:00:00.266357", "end": "2014-05-15 23:28:14.723983", "item": "", "rc": 10, "start": "2014-05-15 23:28:14.457626"}
stdout: Don't run Bundler as root. Bundler can ask for sudo if it is needed, and
installing your bundle as root will break this application for all non-root
users on this machine.
/vagrant_data/Gemfile not found

Please note that, whatever the solution, it cannot involve maintaining two sources of truth for the list of gems needed for Jekyll. Otherwise, we'll end up in the same state as issue #117 :)

This is for dev environment only.

This is the nav that will go in the header across every page:

• SDKs & Tools -> /sdks
• Docs -> /docs
• Blog -> /blog
• More (dropdown, not clickable)
  • Community -> /community

  ---

  • Control Panel -> mycloud.rackspace.com
  • Status -> status.rackspace.com

  ---

  • Knowledge Base -> http://www.rackspace.com/knowledge_center/
  • Developer Forums -> https://community.rackspace.com/developers/default
  • Talk with Support -> http://www.rackspace.com/support/

We're going to have at least a few assets in /js, would be nice to do the right thing here.

/sdks/dot-net/index.html

Currently, when you generate the docs you get a link like this for every heading:

I'd like them to look more like (the github standard for a link to a section).

Most of this I can do rather trivially with CSS, but I'd really like to have the sphinx build autogenerate the character as a # instead of a Paragraph marker. And I'd like to not have to search/replace via JS.

In the development environment VM, the following command is run from the /vagrant_data/site_source directory as the publisher user:

LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 /usr/local/bin/jekyll build --watch --source . --destination /var/www/html/developer.rackspace.com/

This is run by an upstart script, /etc/init/site_source_watcher.conf. It logs at /var/log/upstart/site_source_watcher.log.

The upstart script works as expected. However, the jekyll command shown above takes FOREVER to regenerate the site when a change is made. This task is about investigating that slowness and trying to fix it.

To test this, you can do the following inside the development VM:

1. Stop the upstart script: sudo service site_source_watcher stop
2. Become the publisher user: sudo su - publisher
3. Get yourself a shell for convenience: bash
4. Go into the site_source directory: cd /vagrant_data/site_source
5. Run the jekyll command shown above.
6. In another window make changes to files under the site_source directory and observe the regeneration output and the slowness in the jekyll window.

/sdks/index.html

https://github.com/zroger/jekyll-less

Ideally, this would remove the static css folder in site_source

We want to use highlight.js but Sphinx appears to use highlight- styles by default.

Liquid Exception: Variable '{{dbName1}' was not properly terminated with regexp: /}}/ in docs/databases/samples/create_user.html

See https://docs.google.com/spreadsheets/d/1q8RC8w3OexFL-d_bnTwfI0klpGAwwr8PJ5EfV0xzNWU/edit#gid=0 for what's left to complete.

This is just a tracking issue. You can use the issue # as a reference when committing code samples. No one person is assigned to it since there will likely be multiple people working on these code samples.

This issue should remain open until ALL Getting Started Guides' code samples have been merged.

Both watchers should simply kick off this script.

1. cd /vagrant_data/docs
2. /usr/local/bin/sphinx-build . /usr/local/src/developer.rackspace.com/docs
3. cd /vagrant_data/site_source
4. /usr/local/bin/jekyll --verbose --source . --destination /usr/local/src/developer.rackspace.com
5. rsync /usr/local/src/developer.rackspace.com /var/www/html/developer.rackspace.com arguments as appropriate? -Cav maybe?

/sdks/node-js/index.html

I first observed this on #121, but I just replicated on master. While Vagrant is running, gem install commands (run by hand or through Ansible) sporadically fail with ETIMEDOUT:

smash@tiger ~/writings/developer.rackspace.com (bundle-it-up *) $ gem install bundler --version 1.6.2
ERROR:  Could not find a valid gem 'bundler' (= 1.6.2), here is why:
          Unable to download data from https://rubygems.org/ - Errno::ETIMEDOUT: Operation timed out - connect(2) for "api.rubygems.org" port 443 (https://api.rubygems.org/specs.4.8

But if I halt Vagrant, everything works just fine:

smash@tiger ~/writings/developer.rackspace.com (bundle-it-up *) $ gem install bundler --version 1.6.2
Fetching: bundler-1.6.2.gem (100%)
Successfully installed bundler-1.6.2
1 gem installed

index.html at the _site level is missing. This causes jekyll to throw forbidden errors.

This issue requires HTML/CSS/images derived from the Services mock up. I have requested these assets from our designer, Patrick Deuley. Until we have these assets, I'm moving this issue out of the sprint and into the backlog.

On the current developer.rackspace.com site, blog post URLs looks like this: http://developer.rackspace.com/blog/some-blog-post.html

Currently, for the new developer.rackspace.com site, when jekyll build is run inside site_source, the blog post URLs that are generated look like this: http://developer.rackspace.com/blog/2014/01/09/some-blog-post.html. This needs to be fixed so that the URLs match the ones on the current developer.rackspace.com site. Otherwise existing links will break and SEO will be suffer.

smash@tiger ~/writings/developer.rackspace.com (master=) $ ls -la src/docs/files
total 8
drwxr-xr-x   5 smash  staff   170 May 15 20:36 .
drwxr-xr-x  22 smash  staff   748 May 15 09:40 ..
drwxr-xr-x   3 smash  staff   102 May 15 20:36 .. include:: samples
-rw-r--r--   1 smash  staff  3170 May 15 09:40 quickstart.rst
drwxr-xr-x  14 smash  staff   476 May 15 20:36 samples
smash@tiger ~/writings/developer.rackspace.com (master=) $ 

Notice the directory called ".. include:: samples". That looks... wrong?

This includes shared CSS, header and footer.

Long term, our monitoring strategy should be automatically configured as part of provisioning to ensure it's deterministic and consistent. Not required for initial release.

/community/index.html

Currently, there are three parts of the web site that are each generated separately by their own build tools:

1. The Getting Started docs are generated by sphinx under docs/_build/html,
2. The rest of the web site is generated by jekyll under site_source/_site.

The end-goal is to have the HTML generated by three parts be styled consistently with a shared header and footer. This is probably something that happen during the build process in Jenkins but there might be other/better ways to accomplish the end-goal.

• Copy files from https://github.com/rackerlabs/devsite/tree/master/source/_posts to https://github.com/rackerlabs/developer.rackspace.com/tree/master/site_source/_posts
• Attempt to build (by running jekyll build under site_source) and fix any errors. Repeat until build is successful.

I believe fileschanged executes its command once for each file that changes. Since the build script takes a nontrivial amount of time to complete, changing git branches queues up a ton of build-script executions, which ultimately ends up clobbering resources on the vagrant box.

vagrant@precise64:~$ ps -fu vagrant  
UID        PID  PPID  C STIME TTY          TIME CMD
vagrant  14079     1  0 11:22 ?        00:00:00 /usr/sbin/famd -T 0
vagrant  14135     1 11 11:22 ?        00:21:04 /usr/bin/fileschanged --recursive --exec /vagrant_data/build_site.sh /vagrant_data/src/
vagrant  21956 14135  0 12:29 ?        00:00:00 /bin/bash /vagrant_data/build_site.sh A /vagrant_data/src/docs/cloud-load-balancers/getting-star
vagrant  21976 14135  0 12:29 ?        00:00:00 /bin/bash /vagrant_data/build_site.sh M /vagrant_data/src/docs/cloud-load-balancers/getting-star
vagrant  21996 14135  0 12:29 ?        00:00:00 /bin/bash /vagrant_data/build_site.sh M /vagrant_data/src/docs/cloud-load-balancers/getting-star
vagrant  22014 21976 11 12:29 ?        00:12:31 ruby2.1 /usr/local/bin/jekyll build --source . --destination /tmp/developer.rackspace.com/_site
vagrant  22017 21996 10 12:30 ?        00:11:27 ruby2.1 /usr/local/bin/jekyll build --source . --destination /tmp/developer.rackspace.com/_site
vagrant  22019 21956  9 12:30 ?        00:10:03 ruby2.1 /usr/local/bin/jekyll build --source . --destination /tmp/developer.rackspace.com/_site
vagrant  22104 14135  0 12:31 ?        00:00:00 /bin/bash /vagrant_data/build_site.sh M /vagrant_data/src/docs/cloud-load-balancers/getting-star
vagrant  22118 14135  0 12:31 ?        00:00:00 /bin/bash /vagrant_data/build_site.sh M /vagrant_data/src/docs/cloud-load-balancers/getting-star
vagrant  22182 14135  0 12:31 ?        00:00:00 /bin/bash /vagrant_data/build_site.sh M /vagrant_data/src/docs/cloud-load-balancers/getting-star
# ...

Ideally, we would only run one instance of build_site for each "batch" of file changes, but that's hard to do. Just to braindump a few ideas:

1. Check for a dotfile somewhere at the script's start and immediately exit if it's present. Touch that file right after and rm it at script exit. File-based concurrency control, basically -- although this will cause problems if the script doesn't exit cleanly and has race conditions (unless there's a way to atomically create-if-not-exists, open(O_CREAT | O_EXCL)-style?)
2. The STONITH approach: start with a killall to nuke all the other processes. Ideally the last one launched will win.
3. Find some UNIX-y software that'll manage the "only one process at a time" thing for us. This seems like the sort of thing that someone else has to have written a utility for, right? Then we can configure filewatcher to trigger that utility instead of the script directly.

Prior to launch, we must have active monitoring in place. This should include, at a minimum:

• TCP port check (port 80)
• HTTP content check on index.html
• HTTP content check on blog index page
• HTTP content check on SDK/tools index page

Alerts should go to a real-time list that includes DRG ops staff as well as AgI operations team.

Currently missing:

• Cloud DNS
• Cloud Load Balancers

All getting started guides say "Quick Start for {service}" with the exception of Auto Scale, which says "Quick Start Guide".

In the developer environment, Vagrant establishes a port forwarding rule so that requests made to port 8000 on the host machine are forwarded to port 80 on the development VM. Inside the development VM, nginx is listening for requests on port 80.

By default, when nginx receives requests for URLs that do not end with a trailing slash (e.g. /blog), it will return a 301 redirect to the same URL with a trailing slash appended (e.g. /blog/). The issue is that when it does this redirect, it does not include the port from the Host header (8000 in the dev environment) as-is in the Location header. Here is a sample curl interaction to demonstrate this:

$ curl -v 'http://localhost:8000/docs' 
...
> GET /docs HTTP/1.1
> User-Agent: curl/7.30.0
> Host: localhost:8000
> Accept: */*
> 
< HTTP/1.1 301 Moved Permanently
* Server nginx/1.1.19 is not blacklisted
< Server: nginx/1.1.19
< Date: Tue, 13 May 2014 13:34:40 GMT
< Content-Type: text/html
< Content-Length: 185
< Location: http://localhost/docs/
< Connection: keep-alive

Notice how the Host request header has localhost:8000 in it but the Location response header has http://localhost/docs/ (i.e. no 8000 port) in it.

This is a problem because the HTTP client on the host machine will then try to follow the redirect and request http://localhost/docs/, which does not work because port 80 on the host machine is not being forwarded to port 8000 on the development VM.

Please note that this is only an issue in the developer environment, not in production.

/sdks/php/index.html

• Finish up Ansible scripts to create Jenkins server(s), including job configurations.
• Job should checkout source from GitHub, build site_source (using Jekyll), docs (using Sphinx) and api (using maven), combine all those build artifacts and publish them (via SSH+rsync or something) to the web servers serving the new developer.rackspace.com.

Depends on #74 and #90.

Currently there is a redundancy between https://github.com/rackerlabs/developer.rackspace.com/blob/master/deploy/roles/jekyll/tasks/main.yml#L21-L29 and https://github.com/rackerlabs/developer.rackspace.com/blob/master/Gemfile. This is dangerous as things can get out of sync.

Either remove the Gemfile and Gemfile.lock so the dependencies are defined exclusively in the Ansible role or remove the dependencies from the Ansible role and make it use the Gemfile(.lock) instead. The end result should be that the gems should be defined in exactly one place.

Currently the prod_web.yml Ansible playbook sets up 1 load balancer and 2 web servers in the specified region (via the required RAX_REGION environment variable).

The playbook can be reused to setup a production environment or a staging environment. To do this:

• Have this playbook accept another environment variable, say APP_ENV that could be set to production or staging, defaulting to staging.
• Prepend this variable to various inventory names in the playbook. This will let us easily differentiate a production web server from a staging one in the control panel.
• Prepend this variable to the various inventory group names in the playbook. This will ensure that if the playbook is re-run, it configures to the right group of servers.

We should be able to link any getting-started guide or other documentation that references a region requirement to an authoritative page that lists our regions and what services are supported in them. We should include global (regionless) if applicable. I'm looking at you Monitoring and DNS.

i.e. http://developer.rackspace.com/regions

Example: