bedrock Documentation Release 1.0 Mozilla Sep 27, 2017 Contents 1 Contents 3 1.1 Quickstart................................................3 1.2 Installing Bedrock............................................3 1.3 Vagrant Installation............................................8 1.4 Installing and Learning About the PHP Site............................... 12 1.5 Localization............................................... 18 1.6 Developing on Bedrock......................................... 23 1.7 Front-end testing............................................. 26 1.8 JavaScript Libraries........................................... 28 1.9 How to contribute............................................ 28 1.10 Using Grunt............................................... 31 1.11 Managing Redirects........................................... 32 1.12 Newsletters................................................ 35 1.13 Tabzilla.................................................. 37 1.14 Mozilla.UITour.............................................. 39 1.15 Send to Device widget.......................................... 50 i ii bedrock Documentation, Release 1.0 bedrock is the code name of the new mozilla.org. It is bound to be as shiny, awesome, and open sourcy as always. Perhaps even a little more. bedrock is a web application based on Django. Patches are welcome! Feel free to fork and contribute to this project on Github. Contents 1 bedrock Documentation, Release 1.0 2 Contents CHAPTER 1 Contents Quickstart You can develop and test bedrock without installing anything locally by using Cloud9, which provides a complete development environment via your browser, including unlimited free public workspaces1, which is great for open source projects. Each workspace includes root access to an Ubuntu Docker container, which you can install bedrock and all its depdencies into with the following steps: 1. Fork bedrock on github 2. Sign up or sign in to Cloud9 with your github account2 3. Create a new workspace from your fork using the “Clone from URL” option with a URL in the format [email protected]:mozilla/bedrock.git but with your username instead of mozilla 4. Once your workspace is ready, click the “Start Editing” button 5. In the bash shell, run the command bin/install-c9 Once the install-c9 script completes, you can click the Run Project button to launch the django development server, which will be accessible on a public URL similar to http://bedrock-c9-username.c9.io Installing Bedrock Installation These instructions assume you have git and pip installed. If you don’t have pip installed, you can install it with easy_install pip. Start by getting the source: 1 Public means everything in the workspace is world readable; you can also grant write access to specific cloud9 users and collaboratively edit code in your workspace in real time. 2 Github account integration is optional; if you do not wish to give cloud9 access to push to any repo your github account has access, you may wish to use a deploy key or a machine user account. 3 bedrock Documentation, Release 1.0 $ git clone --recursive git://github.com/mozilla/bedrock.git $ cd bedrock (Make sure you use –recursive so that legal-docs are included) You need to create a virtual environment for Python libraries. Skip the first instruction if you already have virtualenv installed: $ pip install virtualenv # installs virtualenv, skip if already ,!have it $ virtualenv -p python2.7 venv # create a virtual env in the folder ,!`venv` $ source venv/bin/activate # activate the virtual env $ bin/peep.py install -r requirements/dev.txt # installs dependencies Note: The final command above (peep.py) may fail if you have the wrong version of pip. To correct this run the following command: $ pip install -r requirements/pip.txt This will ensure you have the right pip version and that the peep.py tool will work correctly. If you are on OSX and some of the compiled dependencies fails to compile, try explicitly setting the arch flags and try again: $ export ARCHFLAGS="-arch i386 -arch x86_64" $ bin/peep.py install -r requirements/dev.txt If you are on Linux, you will need at least the following packages or their equivalent for your distro: python-dev libxslt-dev Now configure the application to run locally by creating your local settings file: $ cp bedrock/settings/local.py-dist bedrock/settings/local.py You shouldn’t need to customize anything in there yet. Sync the database and all of the external data locally. This gets product-details, security-advisories, credits, release notes, etc: $ bin/sync_all Lastly, you need to have Node.js installed. The node dependencies for running the site are in the repository, but if you’d like to run the JS test suite you’ll need everything, which you can get by running npm install from the root directory of the project. Run the tests Important: We’re working on fixing this, but for now you need the localization files for the tests to pass. See the Localization section below for instructions on checking those out. 4 Chapter 1. Contents bedrock Documentation, Release 1.0 Now that we have everything installed, let’s make sure all of our tests pass. This will be important during development so that you can easily know when you’ve broken something with a change. You should still have your virtualenv activated, so running the tests is as simple as: $ ./manage.py test Note: If your local tests run fine, but when you submit a pull-request our Jenkins (continuous integration service) instance tells you the tests failed, it could be due to the difference in settings between what you have in settings/ local.py and what Jenkins uses: settings/jenkins.py. You can run tests as close to Jenkins as possible by doing the following: $ JENKINS_HOME=1 ./manage.py test This tells Bedrock to use the jenkins settings. This will require you to have a local MySQL database server running and configured correctly, but may help you debug. Alternately you can move your settings/local.py to a backup, copy settings/jenkins.py to settings/local.py and tweak the DB settings yourself to make it work. Make it run To make the server run, make sure you are inside a virtualenv, and then run the server: $ ./manage.py runserver If you are not inside a virtualenv, you can activate it by doing: $ source venv/bin/activate If you get the error “NoneType is not iterable”, you didn’t check out the latest product-details. See the above section for that. Run it with the whole site If you need to run the whole site locally, you’ll need to first set up the PHP side, and then also set up to serve Bedrock from the same Apache server at /b/. That’s because the rewrite rules in the PHP and Apache config assume they can serve requests from Bedrock by rewriting them internally to have a /b/ on the front of their URLs. Important: Before continuing, go get the PHP side working. Then come back here. One way to add Bedrock to your local site, once you have the PHP side working, is to use runserver to serve Bedrock at port 8000 as above, then proxy to it from Apache. The whole virtual server config might end up looking like this: <VirtualHost *:80> ServerName mozilla.local VirtualDocumentRoot"/path/to/mozilla.com" RewriteEngine On RewriteOptions Inherit ProxyPass/b http://localhost:8000 ProxyPassReverse/b http://localhost:8000 ProxyPass/media http://localhost:8000/media ProxyPassReverse/media http://localhost:8000/media 1.2. Installing Bedrock 5 bedrock Documentation, Release 1.0 Include/path/to/bedrock/etc/httpd/ global.conf </VirtualHost> But you might have better success using a real WSGI setup that is closer to what the real servers use. The following configuration is simplified from what the bedrock staging server uses. Assumptions: • A Red Hat or Debian-based Linux distribution. (Other distributions might not have Apache HTTP Server installed and configured the same way.) • Apache HTTP Server with php and mod_wsgi • Subversion mozilla.com checkout at /path/to/mozilla/mozilla.com • Subversion mozilla.org checkout at /path/to/mozilla/mozilla.com/org (ideally as an SVN external) • Bedrock checkout at /path/to/mozilla/bedrock Create a local config files for mozilla.com and mozilla.org: $ cp /path/to/mozilla.com/includes/config.inc.php-dist /path/to/mozilla.com/includes/ ,!config.inc.php $ cp /path/to/mozilla.com/org/includes/config.inc.php-dist /path/to/mozilla.com/org/ ,!includes/config.inc.php` Edit /etc/hosts and add: 127.0.0.1 mozilla.local Apache config - create file /etc/apache2/sites-available/mozilla.com: # Main site at /, django-bedrock at /b <VirtualHost *:80 *:81> ServerName mozilla.local ServerAdmin [email protected] DocumentRoot"/path/to/mozilla/mozilla.com" AddType application/x-httpd-php.php.html DirectoryIndex index.php index.html RewriteEngine On <Directory"/path/to/mozilla.com"> Options MultiViews FollowSymLinks-Indexes AllowOverride All </Directory> RewriteMap org-urls-410 txt:/path/to/mozilla.com/org-urls-410.txt RewriteMap org-urls-301 txt:/path/to/mozilla.com/org-urls-301.txt WSGIDaemonProcess bedrock_local python-path=/path/to/bedrock:/path/to/venv-for- ,!bedrock/lib/python2.7/site-packages WSGIProcessGroup bedrock_local WSGIScriptAlias/b/path/to/bedrock/wsgi/playdoh.wsgi process-group=bedrock_local ,!application-group=bedrock_local Alias/media/path/to/bedrock/media <Directory/path/to/bedrock/media> AllowOverride FileInfo Indexes </Directory> 6 Chapter 1. Contents bedrock Documentation, Release 1.0 Include/path/to/bedrock/etc/httpd/ global.conf </VirtualHost> Then enable the new site, build the css and js files, and finally restart apache: sudo a2ensite mozilla.com sudo a2enmod expires headers actions python manage.py collectstatic sudo service apache2 restart Troubleshooting If you get Django error pages reporting I/O errors for .css files, it’s because not all the .css files were compiled before starting Apache and Apache does not have write permissions in the media directories. Running python manage.py collectstatic should solve it. Remember to run that command again anytime the css or less files change. If you change Python files, either restart Apache or touch playdoh.wsgi, so that the WSGI processes will be restarted and start running the new code.