bedrock/docs/php.rst

369 строки
14 KiB
ReStructuredText

.. This Source Code Form is subject to the terms of the Mozilla Public
.. License, v. 2.0. If a copy of the MPL was not distributed with this
.. file, You can obtain one at http://mozilla.org/MPL/2.0/.
.. _php:
============================================
Installing and Learning About the PHP Site
============================================
The previous version of mozilla.org was written in PHP. The PHP
codebase still serves some of the mozilla.org pages because we haven't
migrated everything over. A request runs through the following stack:
* If the page exists in Bedrock, serve from Bedrock
* If the page exists in the PHP site, serve from PHP
* Else, serve a 404 page
History
=======
The PHP site has a long history and as a result, is a little quirky.
If you are looking to work on the site and/or set it up locally, this
page will be helpful to you.
mozilla.org, mozilla.com, and thunderbird used to be completely
separate sites with different PHP codebases. In 2011 these sites were
merged into one site.
The merge is purely for aesthetics though. In the PHP side of
mozilla.org, a few different PHP codebases coexist beside each other,
and a combination of Apache and PHP magic bind them all together (one
site to rule them all, or something like that).
Installing
==========
.. _apache:
Apache
------
Whether you're installing just `mozilla.com` or also `mozilla.org`, there's
some common configuration required for Apache.
1. Install PHP. On Ubuntu, you can use these commands::
sudo apt-get install libapache2-mod-php5
2. Enable the required modules. On Ubuntu, this should get most of them::
sudo a2enmod actions expires headers php5 proxy proxy_http rewrite status vhost_alias
but if Apache fails to start with errors about unknown directives, that
probably means some other module also needs to be enabled.
Bedrock
-------
The whole site now assumes Bedrock is also available. Even after following
the instructions below, parts of the site will not work until/unless you also
have :ref:`Bedrock running locally<with php>`. Or you might see an old version
of a page from PHP, because the newer version is in Bedrock but the old
version wasn't removed from PHP.
.. _mozilla-com:
mozilla.com
-----------
If you want to just work on the mozilla.com codebase (currently served
at mozilla.org/firefox), follow these steps. You will only get the
product pages. See :ref:`mozilla.org <mozilla-org>` for instructions
on installing the org side of the site. For more details on why
several codebases run the site, see :ref:`How a Request is Handled <merge>`.
.. note:: This assumes you are using Apache with Unix. Windows might have
different steps, please contact us if you need help.
1. Install it with these commands:
::
svn co https://svn.mozilla.org/projects/mozilla.com/trunk mozilla.com
cd mozilla.com/includes
cp config.inc.php-dist config.inc.php
2. Open /includes/config.inc.php and set the `server_name` to "mozilla.local" (or whatever you will use) and `file_root` to the site's path on the filesystem.
3. Set up `mozilla.local` to resolve to localhost. This is different for each OS, but a quick way on Linux/OS X is to add an entry to /etc/hosts::
127.0.0.1 mozilla.local
4. Configure Apache to allow the site to run with a Directory and VirtualHost directive:
This could go in the main Apache configuration file, or
on Ubuntu, you might put this in ``/etc/apache2/sites-available/mozilla.com.conf``.
::
<Directory /path/to/mozilla.com>
Options Includes FollowSymLinks MultiViews Indexes
AllowOverride All
Order Deny,Allow
Allow from all
</Directory>
<VirtualHost *:80>
ServerName mozilla.local
VirtualDocumentRoot "/path/to/mozilla.com"
</VirtualHost>
Make sure to replace ServerName and /path/to/ to the correct values.
On Ubuntu, you would then enable the site with::
sudo a2ensite mozilla.com
5. You *might* need to set the DocumentRoot to the site if you can't load any CSS files. We are looking to fix this.
DocumentRoot "/path/to/mozilla/mozilla.com"
You shouldn't need anything else in the site config for mozilla.com. The `.htaccess` file
at the root of mozilla.com contains the rest of the required configuration.
6. Restart Apache. On Ubuntu::
sudo service apache2 restart
If you go to http://mozilla.local/ you should see a page for downloading Firefox.
.. _mozilla-org:
mozilla.org
-----------
If you need to work on mozilla.org, you need to install it as well.
The installation process is identical to mozilla.com, with a few
tweaks.
.. note:: htaccess files do not work on mozilla.org. If you need to
add anything to htaccess files, you must commit them to the
mozilla.com codebase. See the section below about the merge
for more info.
1. Make sure you install it as a subdirectory underneath mozilla.com named *org*.
::
cd mozilla.com
svn co https://svn.mozilla.org/projects/mozilla.org/trunk org
cd org/includes
cp config.inc.php-dist config.inc.php
2. Open /org/includes/config.inc.php and set the `server_name` to "mozilla.local" (or whatever you will use) and `file_root` to the site's path on the filesystem (including the org subdirectory).
3. In addition, set the 'js_prefix', 'img_prefix', 'style_prefix' config values to '/org'. **That is necessary**.
4. If you need the archive redirects to work, you need to add the RewriteMap directives to your Apache config for the site. Inside the VirtualHost section that you made while installing mozilla.com, add this:
::
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
5. Depending on your system settings, you might see warnings about relying on the system's timezone settings. If you get this, add the following to the config.inc.php for mozilla.org:
::
date_default_timezone_set('America/New_York');
You can look up the correct timezone `here
<http://www.php.net/manual/en/timezones.php>`_.
That should be it. If you go to http://mozilla.local/ (or whatever
local server you set it to) you should see the org home page.
Thunderbird
-----------
The thunderbird site has been completely merged in with mozilla.org,
so you can install it by :ref:`installing mozilla.org <mozilla-org>`. It
will be served at /thunderbird.
.. _merge:
Workflow
========
If you are working on a bug, please follow these steps:
1. Commit your work to trunk
2. Comment on the bug and add the revision in the whiteboard field in the form "r=10000". Multiple revisions should be comma-delimited, like "r=10000,10001". You can add the revision in the comment too if you want people to have a link to the changes.
3. Add the keyword "qawanted" when finished
4. When all the work is done and has been QAed, mark as resolved.
We release a batch of resolved bugs every Tuesday. Other bugs can go
out between releases, but by default resolved bugs tagged with the
current milestone will go out the next Tuesday.
Stage isn't used for much, but it's useful for times when we are very
careful about rolling out something. You typically don't need to worry
about it. When bugs are pushed live, they are pushed to stage and
production at the same time.
Rolling out code
----------------
So you want to rollout a bug into production? If you look at our
workflow, there should be some SVN revisions logged into the
whiteboard of the bug. If not, you need to track down which revisions
to push from the comments.
Once you have this list, you need to merge them to the branches
`tags/stage` and `tags/production`. If the revisions are already
pushed to stage, only do the latter. These are the commands:
::
cd tags/stage
svn merge --ignore-ancestry -c<revs> ../../trunk
svn commit -m 'merged <rev> from trunk for bug <id>'
`<revs>` is a single rev or comma-delimited like "10000,10001,10002".
Do the same for tags/production. Always format the log message like
the above. You must use `--ignore-ancestry` also to avoid bad things.
We wrote a script to automate this if you are doing this a lot. You
can find it it on trunk in `/bin/rollout
<https://github.com/jlongster/mozilla.com/blob/master/bin/rollout>`_.
The usage looks like this:
::
Usage: rollout <bug-id> <revs> <branch>
<revs> and <branch> are optional
$ cd mozilla.com # must have trunk, tags/stage, and tags/production checked out here
$ rollout 654321
Merging into tags/stage...
--- Merging r654321 into '.':
<svn output>
Continue? y/n [n]y
Committing tags/stage...
Merging into tags/production...
--- Merging r654321 into '.':
<svn output>
Continue? y/n [n]y
Committing tags/production...
The script parses the revisions and branch from the whiteboard data in
bugzilla, and merges it from trunk to stage and production. If the
branch is already stage (b=stage in the whiteboard) it just merges it
to production.
After it does the merges, it asks you if you want to continue. If you
saw conflicts, you shouldn't continue and you should fix the conflicts
and either finish the rollout by hand or update the bugzilla
whiteboard and run the command again.
How a Request is Handled
========================
Magic should always be documented, so let's look at exactly how all
the PHP sites work together to handle a mozilla.org request.
mozilla.org is made up of three sites:
* mozilla.com (the product pages)
* mozilla.org (mofo)
* mozillamessaging.com (thunderbird)
These three sites are now all merged into http://mozilla.org/.
However, on the server a request can be handled by three different
codebases. We'll refer to the mozilla.com codebase as `moco`,
mozilla.org codebase as `mofo`, and messaging as `thunderbird`.
moco is the primary codebase. A request goes through the following steps:
* If the URL exists in the mofo codebase, load the page from there
* If the URL exists in the thunderbird codebase, load from there
* Else, let moco handle the URL like normal
The merge magic is installed into moco's htaccess and PHP files. We
let moco become the primary codebase because if there's any error in
the merge code, we can't afford to break the main Firefox product
pages. There's also more developer attention on moco.
**Special Note**: Only mozilla.com's .htaccess files are processed by
Apache. All the others have been merged in so you shouldn't add
anything to them. Please add all htaccess rules inthe mozilla.com
codebase.
Merge Magic
-----------
How we implement the merge is really important. Performance, site
breakage, and amount of work to move things around are all serious
considerations. The merge is meant to be temporary as the site is
moving to Python, so it's not worth the effort to literally merge all
the PHP code together.
It's also important to still allow the mofo and moco codebases to be
run individually. We don't want to suddenly break it for people who
have it locally checked out (short-term wise). Finally, the code of
each site also dictated possible solutions. There's a lot of edge
cases in each site so need to make sure we don't break anything.
Here's how the merge magic was implemented:
**Short version:**
* Check out the mofo codebase under moco as the subdirectory *org*.
* Redirect all mofo URLs to a PHP handler which loads those pages, do
the same for thunderbird
* Fix loading of images, css, and js by setting prefix config values and more rewrites
* Merge .htaccess files into the moco codebase
**Long version:**
* Check out the mofo codebase under moco as the subdirectory *org*.
* Thunderbird is a folder under org, at /org/thunderbird
* Generate a list of top-level folders in the org site and use Apache
rewrites to `redirect all those URLs to a special php handler <https://github.com/jlongster/mozilla.com/blob/813aa578d7850f79d9f6b5274051f0f2175dd957/.htaccess#L805>`_
* Write the `special php handler
<https://github.com/jlongster/mozilla.com/blob/813aa578d7850f79d9f6b5274051f0f2175dd957/includes/org-handler.php>`_
to load mofo pages. This is basically a port of mofo's prefetch.php
* Write a `similar handler
<https://github.com/jlongster/mozilla.com/blob/813aa578d7850f79d9f6b5274051f0f2175dd957/includes/thunderbird-handler.php>`_
for the thunderbird pages and `redirect all /thunderbird URLs to it <https://github.com/jlongster/mozilla.com/blob/813aa578d7850f79d9f6b5274051f0f2175dd957/.htaccess#L616>`_
* Fix loading of assets
* `Set config values
<https://github.com/jlongster/mozilla.org/blob/master/includes/config.inc.php-dist#L96>`_
to load assets with the "/org" prefix
* For bad code that doesn't use the config, use `apache rewrites
<https://github.com/jlongster/mozilla.com/blob/813aa578d7850f79d9f6b5274051f0f2175dd957/.htaccess#L579>`_
to redirect `images` and `script` to the respective folder in
"/org". These two folders don't conflict with the moco codebase.
The `style` directory conflicts, so make sure all code uses the
config prefix value.
* `Redirect any other asset directory
<https://github.com/jlongster/mozilla.com/blob/813aa578d7850f79d9f6b5274051f0f2175dd957/.htaccess#L590>`_
to use the "/org" prefix (/thunderbird/img/, etc)
* Merge .htacess files
* The biggest side effect of this is that only moco htaccess files
are processed, but we should consolidate things anyway
* `Move the redirects
<https://github.com/jlongster/mozilla.com/blob/813aa578d7850f79d9f6b5274051f0f2175dd957/.htaccess#L619>`_
and other appropriate rules from mofo's htaccess to moco's
* `Optimize the crazy amount of 301 and 410 redirects
<https://github.com/jlongster/mozilla.com/blob/813aa578d7850f79d9f6b5274051f0f2175dd957/.htaccess#L602>`_
from mofo, mostly archive redirects, using RewriteMap
* Test to make sure everything's working, implement special rewrites
or org-handler.php hacks to fix any breakage
* Check file extensions for any leftover static types and `rewrite them <https://github.com/jlongster/mozilla.com/blob/master/.htaccess#L582>`_ to be served by Apache
The final result is the moco codebase which dispatches a lot of URLs
to the mofo and thunderbird codebases.