diff --git a/02.importing/01.get-database-files/docs.md b/02.importing/01.get-database-files/docs.md
index 7af7424..238aa3d 100644
--- a/02.importing/01.get-database-files/docs.md
+++ b/02.importing/01.get-database-files/docs.md
@@ -1,7 +1,7 @@
---
title: Get Your Database and Files Into Aegir
slug: get-database-files
-menu: Database and Files
+menu: Get Database and Files
date: 08-08-2016
published: true
visible: true
@@ -14,95 +14,84 @@ routes:
- /prepare-your-database-files
---
+Get Your Database and Files Into Aegir
+
To import your site into Aegir, the first step is to get your database
and files. You need to copy them from the old site and upload them to
your Aegir account.
-Task: Get Your Database and Files
----------------------------------
+h2. Task: Get Your Database and Files
-### Get the Database
+h3. Get the Database
-1. Get a full database dump of your old site as an sql file.
+# Get a full database dump of your old site as an sql file.
-**** You can use a database management tool, such as phpMyAdmin or
-Chive.
+** You can use a database management tool, such as phpMyAdmin or Chive.
-**** Make sure your dump includes the DROP lines. For example,
-`` DROP TABLE IF EXISTS `access`; ``
+** Make sure your dump includes the DROP lines. For example, @DROP TABLE IF EXISTS `access`;@
-**** Or, use the [Backup and Migrate module.](backup-migrate) The backup
-archive includes a database dump as a file ending in `.sql`
+** Or, use the "Backup and Migrate module.":backup-migrate The backup archive includes a database dump as a file ending in @.sql@
-1. If your old database uses table prefixes, you'll need to remove
- these prefixes in the sql file. See "Don't Use Table Prefixes in
- Your Database" below.
+# If your old database uses table prefixes, you'll need to remove
+ these prefixes in the sql file. See "Don't Use Table Prefixes in
+ Your Database" below.
-1. Upload this sql file to `~/static/`.
+# Upload this sql file to @~/static/@.
-### Get the Files
+h3. Get the Files
-1. Upload the full Drupal root of your old site to a directory in
- `~/static/`. Example: `~/static/old-site/`. Tools for uploading
- include:
+# Upload the full Drupal root of your old site to a directory in @~/static/@. Example: @~/static/old-site/@. Tools for uploading include:
-**** SFTP/FTPS
+** SFTP/FTPS
-**** `rsync`
+** @rsync@
-1. Fix the permissions with this command:
- `chmod -R 775 ~/static/old-site/`
+# Fix the permissions with this command: @chmod -R 775 ~/static/old-site/@
-1. Fix the `files/` permissions with a separate command: chmod -R
- 777 ~/static/old-site/sites/default/files/
+# Fix the @files/@ permissions with a separate command: chmod -R 777 ~/static/old-site/sites/default/files/
-**** Note the **777**, not **775**.
+** Note the *777*, not *775*.
-**** If you have also stored files in `sites/foo.com/files`, then fix
-those permissions as well: chmod -R 777
-~/static/old-site/sites/foo.com/files/
+** If you have also stored files in @sites/foo.com/files@, then fix those permissions as well: chmod -R 777 ~/static/old-site/sites/foo.com/files/
-**** Ignore any "Operation not permitted" errors (see below).
+** Ignore any "Operation not permitted" errors (see below).
-1. If your site will be on a new custom platform, you'll also need to
- add your custom platform before you can
- proceed. Follow the steps in [this doc](add-custom-platform)
+# If your site will be on a new custom platform, you'll also need to
+ add your custom platform before you can
+ proceed. Follow the steps in "this doc":add-custom-platform
-Conclusion: Now Get Your Site Into Aegir
-----------------------------------------
+h2. Conclusion: Now Get Your Site Into Aegir
With your files and database on your account, you can now proceed to
-[get your site into Aegir](get-site-into-aegir).
+ "get your site into Aegir":get-site-into-aegir.
-More Information
-----------------
+h2. More Information
-### Don't Use Table Prefixes in Your Database
+h3. Don't Use Table Prefixes in Your Database
-If your old database used table prefixes, with names like `mydb_users`
-instead of `users`, you'll need to remove these prefixes from your
+If your old database used table prefixes, with names like @mydb_users@
+instead of @users@, you'll need to remove these prefixes from your
database dump. Aegir doesn't support table prefixes. Each site gets
its own database.
Since the database dump is a plain text file, you can remove these
prefixes with a simple "find and replace" in your favorite text editor.
-If your prefix is `mydb_`, you should be able to remove these prefixes
-quickly. `mydb_user` becomes `user`, and so on.
+If your prefix is @mydb_@, you should be able to remove these prefixes
+quickly. @mydb_user@ becomes @user@, and so on.
-### "Operation Not Permitted"?
+h3. "Operation Not Permitted"?
-When changing permissions on a `files` directory with `chmod`, you may
-get errors like `Operation not permitted`. You can safely *ignore
+When changing permissions on a @files@ directory with @chmod@, you may
+get errors like @Operation not permitted@. You can safely *ignore
these errors*.
Although your FTPS/SSH user is not an owner of this directory, these
-`chmod` commands are still required, because they will set correct
+@chmod@ commands are still required, because they will set correct
permissions for the files you upload.
-References
-----------
+h2. References
-[get your site onto Aegir](get-site-into-aegir).
+"get your site onto Aegir":get-site-into-aegir.
[get-site-into-aegir]
diff --git a/02.importing/02.import-site-into-aegir/docs.md b/02.importing/02.import-site-into-aegir/docs.md
index cfe4933..3119fae 100644
--- a/02.importing/02.import-site-into-aegir/docs.md
+++ b/02.importing/02.import-site-into-aegir/docs.md
@@ -15,181 +15,163 @@ routes:
- /import-your-sites-to-aegir-in-8-easy-steps-109
---
+Get Your Site Into Aegir
+
To import your site into Aegir, you must first
-[get your database and files into your Aegir
-account](get-database-files).
+"get your database and files into your Aegir account":get-database-files.
Then, you can follow the steps in this doc to set up your new site.
-Task: Import Your Site Into Aegir
----------------------------------
+h2. Task: Import Your Site Into Aegir
-Importing your old site onto an Aegir [platform](platform) is
-straightforward. Follow
+Importing your old site onto an Aegir "platform":platform is straightforward. Follow
each step carefully, and you should have no problems.
-1. Get your database and files into your Aegir account, following
- [the steps in this doc](get-database-files).
+# Get your database and files into your Aegir account, following
+ "the steps in this doc":get-database-files.
-1. If your site will be on a new custom platform, you'll also need to
- add your custom platform before you can
- proceed. Follow the steps in [this doc](add-custom-platform)
+# If your site will be on a new custom platform, you'll also need to
+ add your custom platform before you can
+ proceed. Follow the steps in "this doc":add-custom-platform
-1. [Create a new site](new-site-built-in) on your target platform.
- Use your **actual domain name**. If the site is `foo.com`, use
- `foo.com`, not some temporary domain or subdomain.
+# "Create a new site":new-site-built-in on your target platform.
+Use your *actual domain name*. If the site is @foo.com@, use
+@foo.com@, not some temporary domain or subdomain.
-**** If you have been developing the site locally, see "Why Use the
-Final Domain, Then Rename Twice?" below.
+** If you have been developing the site locally, see "Why Use the Final Domain, Then Rename Twice?" below.
-1. Copy all the old site's `files` into `sites/foo.com/files/` on the
- new site.
+# Copy all the old site's @files@ into @sites/foo.com/files/@ on the new site.
-**** Example:
-`cp -af ~/static/old-site/sites/default/files/* /path/to/platform/sites/foo.com/files/`
+** Example: @cp -af ~/static/old-site/sites/default/files/* /path/to/platform/sites/foo.com/files/@
-**** If you have also stored files in `sites/foo.com/files`, copy those
-files as well.
+** If you have also stored files in @sites/foo.com/files@, copy those files as well.
-1. If your site used additional modules at `sites/all/modules/` and/or
- `sites/foo.com/modules`, you need to copy them:
+# If your site used additional modules at @sites/all/modules/@ and/or
+ @sites/foo.com/modules@, you need to copy them:
-## Copy any "contrib" modules (modules you downloaded from
-drupal.org)
-from their directory within `~/static/old-site/sites/` into
-`sites/all/modules` on the target platform.
+## Copy any "contrib" modules (modules you downloaded from drupal.org)
+ from their directory within @~/static/old-site/sites/@ into
+ @sites/all/modules@ on the target platform.
-***** Look for modules in all possible locations on the old site:
-`sites/all/modules`, `sites/default/modules`, and
-`sites/foo.com/modules`. No matter where you stored them, contrib
-modules should almost always go into `sites/all/modules` on the target
-platform. (See "Always Put Contrib Modules In `sites/all/modules`"
-below.)
+*** Look for modules in all possible locations on the old site:
+ @sites/all/modules@, @sites/default/modules@, and
+ @sites/foo.com/modules@. No matter where you stored them, contrib
+ modules should almost always go into @sites/all/modules@ on the target
+ platform. (See "Always Put Contrib Modules In @sites/all/modules@"
+ below.)
-***** If, instead of copying old modules, you download any modules
-directly from `drupal.org` into the target platform, make sure to fix
-permissions with `chmod -R 775`.
+*** If, instead of copying old modules, you download any modules
+ directly from @drupal.org@ into the target platform, make sure to fix
+ permissions with @chmod -R 775@.
-## Copy any "custom" modules for this site into
-`sites/foo.com/modules`.
+## Copy any "custom" modules for this site into @sites/foo.com/modules@.
## Repeat these steps for themes and libraries.
-***** Contrib themes go into `sites/all/themes`, custom themes into
-`sites/foo.com/themes`.
+*** Contrib themes go into @sites/all/themes@, custom themes into @sites/foo.com/themes@.
-***** Libraries go into `sites/all/libraries`, unless module
-documentation specifies otherwise.
+*** Libraries go into @sites/all/libraries@, unless module documentation specifies otherwise.
-1. Import your uploaded database into the new site with `drush sqlc`.
- Example commands:
+# Import your uploaded database into the new site with @drush sqlc@. Example commands:
-## `cd /path/to/platform/sites/foo.com/`
+## @cd /path/to/platform/sites/foo.com/@
-## `drush sqlc < /data/disk/USER/static/dump.sql`
+## @drush sqlc < /data/disk/USER/static/dump.sql@
-***** Note the full path to the dump file. Don't use a relative path,
-like `~/static`.
+*** Note the full path to the dump file. Don't use a relative path, like @~/static@.
-***** Replace USER with your [BOA](boa) username. This is your FTP/SSH
-username
-minus the ending `.ftp`. If your FTP/SSH username is `12345678.ftp`,
-your BOA username is `12345678`. Your SSH username always appears in
-your SSH prompt.
+*** Replace USER with your "BOA":boa username. This is your FTP/SSH username
+ minus the ending @.ftp@. If your FTP/SSH username is @12345678.ftp@,
+ your BOA username is @12345678@. Your SSH username always appears in
+ your SSH prompt.
## Rebuild the new site's registry.
-***** Use the "Rebuild Registry" task in Aegir.
+*** Use the "Rebuild Registry" task in Aegir.
-***** Or `cd` to `sites/foo.com/` and run `drush rr`.
+*** Or @cd@ to @sites/foo.com/@ and run @drush rr@.
-1. In Aegir, rename the site with the "Migrate" task **twice**.
+# In Aegir, rename the site with the "Migrate" task *twice*.
-## First rename the site to a temporary subdomain (example:
-`temp.foo.com`).
+## First rename the site to a temporary subdomain (example: @temp.foo.com@).
-## Then rename the site back to your final domain (`foo.com`).
+## Then rename the site back to your final domain (@foo.com@).
-***** (See "Why Use the Final Domain, Then Rename Twice?" below.)
+*** (See "Why Use the Final Domain, Then Rename Twice?" below.)
-1. Finally, run the "Verify" task on the site.
+# Finally, run the "Verify" task on the site.
With this final "Verify", all paths to images should be properly
-rewritten, both in the `files` table and in the `node_revision` table.
+rewritten, both in the @files@ table and in the @node_revision@ table.
Done! Enjoy your new site.
-More Information
-----------------
+h2. More Information
To avoid potential problems, you may want to read the following
information before you import your first site.
-### Does Your Drupal 6 or Drupal 5 Site Have to Be Based on Pressflow?
+h3. Does Your Drupal 6 or Drupal 5 Site Have to Be Based on Pressflow?
We do not use vanilla Drupal for our Drupal 6 or Drupal 5 platforms.
-Instead, we use [Pressflow](pressflow).
+Instead, we use "Pressflow":pressflow.
However, we expect that your Drupal 6 or Drupal 5 site is probably
based on vanilla Drupal. No problem. We suggest that you:
-1. [Make a custom platform](add-custom-platform) based on your
- old environment.
+# "Make a custom platform":add-custom-platform based on your old environment.
-1. Import your site to this custom platform.
+# Import your site to this custom platform.
-1. Migrate your site onto a Pressflow platform:
+# Migrate your site onto a Pressflow platform:
-**** You can use one of our built-in Pressflow platforms.
+** You can use one of our built-in Pressflow platforms.
-**** Or you can create your own platform based on Pressflow core.
+** Or you can create your own platform based on Pressflow core.
-Note that **Pressflow is required** for all *live* Drupal 6 and Drupal
-5
+Note that *Pressflow is required* for all _live_ Drupal 6 and Drupal 5
sites. You may not build a custom platform based on vanilla Drupal 6
or Drupal 5, except as a temporary platform to use while migrating
your old sites to Pressflow.
-Please migrate your site to Pressflow **before pointing a live domain**
+Please migrate your site to Pressflow *before pointing a live domain*
name to your Aegir instance IP address. Running vanilla Drupal 6 or
Drupal 5 sites is not allowed, and breaks
-our [Acceptable Use Policy](acceptable-use-policy).
+our "Acceptable Use Policy":acceptable-use-policy.
-Also, with the release of Drupal 7, **Drupal 5 is no longer officially
-supported**,
-so you should upgrade to a Pressflow-based Drupal 6 platform
-immediately.
+Also, with the release of Drupal 7, *Drupal 5 is no longer officially supported*,
+so you should upgrade to a Pressflow-based Drupal 6 platform immediately.
-### If Your `files` Directory Is Over 500MB
+h3. If Your @files@ Directory Is Over 500MB
-When your site's `files/` directory is big (500MB or more), it should
-be moved to a directory in `~/static`, and then symlinked back to
-`sites/foo.com/files`.
+When your site's @files/@ directory is big (500MB or more), it should
+be moved to a directory in @~/static@, and then symlinked back to
+@sites/foo.com/files@.
Several Aegir tasks create a full, compressed archive of the entire
-`sites/foo.com/` directory. If the `files/` directory is too big,
+@sites/foo.com/@ directory. If the @files/@ directory is too big,
these tasks will fail, because the servers run out of RAM and CPU. By
using a symlink, these archives will only store the link, instead of
all the actual files.
Root access is required to make this link. On Omega8.cc, you can't do
-this yourself, but please [contact us](support), and we'll be happy to
+this yourself, but please "contact us":support, and we'll be happy to
make this symlink for you.
If you have root access, the steps might look like this:
- mv /path/to/platform/sites/foo.com/files /data/disk/USER/static/foo.com_files
- ln -s /data/disk/USER/static/foo.com_files /path/to/platform/sites/foo.com/files
+bc. mv /path/to/platform/sites/foo.com/files /data/disk/USER/static/foo.com_files
+ln -s /data/disk/USER/static/foo.com_files /path/to/platform/sites/foo.com/files
Replace USER with your BOA username.
-### Always Put Contrib Modules in `sites/all/modules/`
+h3. Always Put Contrib Modules in @sites/all/modules/@
In normal Drupal, it may not seem to matter much whether you store
-modules in `sites/all/modules`, `sites/default/modules`, or the
-site-specific directory, such as `sites/foo.com/modules`.
+modules in @sites/all/modules@, @sites/default/modules@, or the
+site-specific directory, such as @sites/foo.com/modules@.
But on Aegir, it's critical that you store all "contrib" modules
-(modules you download from drupal.org) in `sites/all/modules`. This is
+(modules you download from drupal.org) in @sites/all/modules@. This is
the platform-wide directory. This single copy of the module will be
used for all the sites.
@@ -198,55 +180,51 @@ a new platform, Aegir will help, comparing the module versions on both
platforms, applying needed database updates, and saving a backup in
case anything breaks.
-If you instead store a contrib module in `sites/foo.com/modules`, you
-lose all
+If you instead store a contrib module in @sites/foo.com/modules@, you lose all
these benefits. In a migration, Aegir ignores everything in
-`sites/foo.com/`, and simply copies the files to the new platform.
+@sites/foo.com/@, and simply copies the files to the new platform.
Plus, you can easily forget that you stashed a copy here. Even if you
migrate the site to a platform with a newer version, the old, insecure
-copy of the module will [override](override-module) the new version.
+copy of the module will "override":override-module the new version.
-You should only use `sites/foo.com/modules` for custom, one-off
+You should only use @sites/foo.com/modules@ for custom, one-off
modules that you write yourself, and are unique to this site.
These rules also apply to themes. Of course, many sites have a unique,
custom theme or subtheme, and it makes sense to store this in
-`sites/foo.com/themes`.
+@sites/foo.com/themes@.
-### Why Use the Final Domain, Then Rename Twice?
+h3. Why Use the Final Domain, Then Rename Twice?
When you create the blank site, why must you use your final, live
-domain name (like `foo.com`), then rename the site twice? This process
+domain name (like @foo.com@), then rename the site twice? This process
ensures that all the paths saved in your database are properly
rewritten.
-For instance, an image stored at `sites/default/files/image.png` must
-get its path rewritten to `sites/foo.com/files/image.png`.
+For instance, an image stored at @sites/default/files/image.png@ must
+get its path rewritten to @sites/foo.com/files/image.png@.
-This renaming process should fix all paths, both in the `files` table
-and also
+This renaming process should fix all paths, both in the @files@ table and also
in your content.
However, there are places where hardcoded paths can't be replaced
automatically. One example is your custom theme settings. If any paths
are still broken, you'll need to fix them manually.
-#### If You Have Been Developing the Site Locally
+h4. If You Have Been Developing the Site Locally
-Note: If you have been **developing this site locally**, with a name
-like
-`domain.local`, but you now want it to be a live site, like `foo.com`,
+Note: If you have been *developing this site locally*, with a name like
+@domain.local@, but you now want it to be a live site, like @foo.com@,
the steps are slightly different:
-1. Create the initial site with the **local name** (like
- `domain.local`),
- instead of the final domain name.
+# Create the initial site with the *local name* (like @domain.local@),
+ instead of the final domain name.
+
+# Then, when the time comes to rename the site twice, follow the steps
+ as usual. Rename to a temporary domain name, then to the final
+ domain name (@foo.com@).
-1. Then, when the time comes to rename the site twice, follow the
- steps
- as usual. Rename to a temporary domain name, then to the final
- domain name (`foo.com`).
[add-custom-platform]
[built-in-platform-list]
diff --git a/03.managing/01.good-habits/chapter.md b/03.managing/01.good-habits/chapter.md
new file mode 100644
index 0000000..2d73a93
--- /dev/null
+++ b/03.managing/01.good-habits/chapter.md
@@ -0,0 +1,15 @@
+---
+title: Good Habits
+menu: Good Habits
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+---
+
+### Chapter 3.1
+
+# Good Habits
+
+Learn useful rules which will make managing Drupal sites with Aegir easier.
diff --git a/03.managing/01.good-habits/file-dir-perms/docs.md b/03.managing/01.good-habits/file-dir-perms/docs.md
new file mode 100644
index 0000000..f6ed372
--- /dev/null
+++ b/03.managing/01.good-habits/file-dir-perms/docs.md
@@ -0,0 +1,120 @@
+---
+title: TITLE
+slug: URI
+menu: MENU
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+routes:
+ aliases:
+ - /URI
+---
+
+Set Correct Permissions for Files You Copy Into Aegir
+
+When you copy files or directories into Aegir, Aegir will _usually_
+set the correct permissions. However, to avoid headaches, you should
+understand when and how to set correct permissions manually.
+
+h2. Task: Set Correct Permissions For Files You Copy
+
+These steps will set all possible permissions for your site.
+
+# "@ssh@ in":ftp-ssh-access to your Aegir account
+
+# @cd@ to the site-specific directory for your Aegir site. If your
+ site is @foo.com@, this will be @sites/foo.com/@ in the "platform":platform
+ directory.
+
+# @chmod -R 775 libraries/* modules/* themes/*@
+
+# @chmod -R 777 files/*@
+
+** Use *777* here, not *775*
+
+** Ignore any "Operation not permitted" warnings.
+
+# @cd@ into @sites/all@.
+
+# @chmod -R 775 libraries/* modules/* themes/*@
+
+# Now run the @Verify@ task on every "platform":platform
+ and site affected by these new files and directories.
+
+h2. More Information
+
+h3. When Do You Need to Set Permissions Manually?
+
+Aegir *will* set correct permissions automatically when you upload
+files or directories using *SFTP* or *FTPS*.
+
+The exception are files in @sites/foo.com/files/@. If you *overwrite*
+a file that needs to be writable by the web server, you can cause
+problems, such as a broken layout.
+
+Aegir *will not* set correct permissions when:
+
+* files have been transferred via @rsync@ or @scp@ on the command line
+* files have been downloaded with @drush@ on the command line
+* files have been extracted from @tar@ or @zip@ archives on the command line
+
+Every morning (in the local timezone for your server/datacenter), a
+"BOA":boa maintenance script will automatically fix all these
+permissions.
+
+However, if you run Aegir tasks while the permissions are still incorrect,
+you can cause problems. You should fix permissions
+manually *before you run any Aegir tasks*.
+
+h3. What If You Don't Set These Permissions?
+
+* You can *lose write permissions* to your uploaded files if you run
+ the @Clone@ or @Migrate@ task.
+
+* The *web server may lose write permissions*, which can break your
+ site layout. Many site layouts require the web server to write
+ temporary files to the @files/@ directory.
+
+These issues will not resolve until the maintenance script runs in the
+morning.
+
+h3. Must You Set Permissions After Updates?
+
+*Yes*. When you download updated libraries, modules, or themes, these
+ are new files. You must set correct permissions, just as you did with
+ the original files.
+
+h3. Which Directories Cannot Be Changed?
+
+Never try to @chmod@ the @files/@, @modules/@, @themes/@ or
+@libraries/@ directories themselves. Instead, @chmod@ their
+subdirectories and files, by adding the @-R@ switch and an asterisk (@*@).
+
+This command will *fail*:
+
+@chmod 777 files/@
+
+But this command is *correct*:
+
+@chmod 777 -R files/*@
+
+h3. "Operation Not Permitted"?
+
+If you @ssh@ in and set correct permissions within the @files/@
+directory, you may see this error: @Operation not permitted.@ This is
+expected, because your SSH user is neither an owner of this directory
+nor of any files owned or created by the web server.
+
+But this error can safely be ignored. The command will still set
+correct permissions for any files you have uploaded.
+
+h2. References
+
+"Keeping Aegir Informed With Aegir Tasks":keeping-aegir-informed
+
+[ftp-ssh-access]
+[platform]
+[sites-all-modules]
+[keeping-aegir-informed]
diff --git a/03.managing/01.good-habits/keeping-aegir-informed/docs.md b/03.managing/01.good-habits/keeping-aegir-informed/docs.md
new file mode 100644
index 0000000..412374a
--- /dev/null
+++ b/03.managing/01.good-habits/keeping-aegir-informed/docs.md
@@ -0,0 +1,49 @@
+---
+title: TITLE
+slug: URI
+menu: MENU
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+routes:
+ aliases:
+ - /URI
+---
+
+When to Run "Verify" Before Other Aegir Tasks
+
+Before you run certain Aegir tasks, it's a good idea to run @Verify@.
+Although some tasks include @Verify@ automatically, a manual @Verify@
+lets you troubleshoot problems before trying to run a complex task.
+
+h2. Task: Verify Before Other Aegir Tasks
+
+* If you have copied any modules, themes, or libraries into this
+ platform within the last 24 hours, you may need to
+ "set correct permissions":file-dir-perms and run @Verify@ on both this platform
+ and each of its sites. Make sure to @Verify@ before running any
+ other Aegir tasks.
+
+* Before running @Clone@, run @Verify@ on the site and its platform.
+
+* After running @Clone@, run @Verify@ on both the original and the cloned sites.
+
+* Before running @Migrate@, run @Verify@ on the site and on both the
+ current and the target platforms.
+
+* To "*rename a site*":rename-task, use @Migrate@, but
+ *keep the site on the same platform*.
+ (Never change a site's name and platform in the same
+ step. This can lead to irreversible breakage.)
+
+h2. References
+
+"Set Correct Permissions for Files You Copy Into Aegir":file-dir-perms
+
+"Rename Your Aegir Site":rename-task
+
+[ssh]
+[file-dir-perms]
+[rename-task]
diff --git a/03.managing/modules/add-module-site/docs.md b/03.managing/02.modules/add-module-site/docs.md
similarity index 54%
rename from 03.managing/modules/add-module-site/docs.md
rename to 03.managing/02.modules/add-module-site/docs.md
index c98268d..8ea1254 100644
--- a/03.managing/modules/add-module-site/docs.md
+++ b/03.managing/02.modules/add-module-site/docs.md
@@ -11,65 +11,63 @@ routes:
aliases:
- /URI
---
+
You can add any module or theme, either for the entire platform or for
a particular site. In general, if you download the module from
drupal.org, you should add it to the entire platform. If you have made
the module or theme yourself, and it is only for one site, it is safe
to add it to the site.
-*Adding* a module does not automatically *enable* it. You can add a
+_Adding_ a module does not automatically _enable_ it. You can add a
module to a platform even if only one site will have it enabled.
-Step-by-Step: Add a Module or Theme to One Site
------------------------------------------------
+h2. Step-by-Step: Add a Module or Theme to One Site
Caution: you should only use this method for a module or theme that
you maintain yourself and is unique to this site.
-1. Upload your module or theme to the site-specific directory. If your
- site is `foo.com`, this will be `sites/foo.com/modules/` or
- `sites/foo.com/themes/`.
+# Upload your module or theme to the site-specific directory. If your
+ site is @foo.com@, this will be @sites/foo.com/modules/@ or
+ @sites/foo.com/themes/@.
+
+# Within this directory, run @chmod -R 775@ to set correct permissions.
-1. Within this directory, run `chmod -R 775` to set
- correct permissions.
+# Rebuild the registry with @drush rr@ or the @Rebuild registry@ Aegir task for the site.
-1. Rebuild the registry with `drush rr` or the `Rebuild registry` Aegir
- task for the site.
+# Enable the module.
-1. Enable the module.
-### Avoid Breaking Your Site(s)
+h3. Avoid Breaking Your Site(s)
-Adding a new module can break your site. You should always **clone your
-live site** and
-**test the new module or theme on the clone**.
+Adding a new module can break your site. You should always *clone your live site* and
+ *test the new module or theme on the clone*.
In general, a new module can't cause damage unless you enable it. In
very rare cases, the mere presence of a module directory can cause
problems for other modules, but this is unusual.
-Overrides are even more dangerous, since they *automatically* upgrade
+Overrides are even more dangerous, since they _automatically_ upgrade
(or downgrade!) the site, with no built-in way to roll back your
changes. If you make this upgrade for the platform, you could break
all the sites in one fell stroke.
Instead, make a new platform, with the new versions of the modules.
-Then [migrate each site to the new platform](migrate-platform). If you
+Then "migrate each site to the new platform":migrate-platform. If you
follow all the steps, Aegir protects your sites from permanent damage.
You can safely restore your sites if they break.
-### Always Put Contrib Modules in `sites/all/modules`
+h3. Always Put Contrib Modules in @sites/all/modules@
When you upload a module from drupal.org, it should go into
-`sites/all/modules`. Same for themes. If you download it, put it in
-`sites/all/themes`. You want one copy for the whole platform.
+@sites/all/modules@. Same for themes. If you download it, put it in
+@sites/all/themes@. You want one copy for the whole platform.
If you instead put a contrib module in the site-specific
-`sites/foo.com/modules/`, you will eventually forget about it, and
-this **old module will make your site insecure**. Even if you upgrade
-the platform version of this module in `sites/all/modules`, your old,
+@sites/foo.com/modules/@, you will eventually forget about it, and
+this *old module will make your site insecure*. Even if you upgrade
+the platform version of this module in @sites/all/modules@, your old,
insecure, site-specific version will silently override it.
-The only exception is if you *want* to override a module on a
+The only exception is if you _want_ to override a module on a
particular site. But the safe option is to prepare an upgraded
platform and migrate the site.
diff --git a/03.managing/modules/advagg/docs.md b/03.managing/02.modules/advagg/docs.md
similarity index 55%
rename from 03.managing/modules/advagg/docs.md
rename to 03.managing/02.modules/advagg/docs.md
index f71f266..fe892aa 100644
--- a/03.managing/modules/advagg/docs.md
+++ b/03.managing/02.modules/advagg/docs.md
@@ -11,81 +11,71 @@ routes:
aliases:
- /URI
---
+
How to Use the AdvAgg Module on Aegir
Does the layout on your Drupal site break whenever you clear the
cache? If so, you may need the AdvAgg module.
-Problem: Clearing Caches Breaks the Layout
-------------------------------------------
+h2. Problem: Clearing Caches Breaks the Layout
When you're developing a web site, especially the theme, you have to
clear the caches to see the changes you make to CSS and Javascript.
-However, when you clear the caches, the CSS and Javascript seem to
-vanish.
+However, when you clear the caches, the CSS and Javascript seem to vanish.
Your site layout breaks, like it's 1999.
-Solution: Enable the built-in AdvAgg Module
--------------------------------------------
+h2. Solution: Enable the built-in AdvAgg Module
-The problem is that CSS and Javascript files are being *aggregated*
+The problem is that CSS and Javascript files are being _aggregated_
(see below for an explanation). You can solve this problem with the
-[AdvAgg](http://drupal.org/project/advagg) module. This module requires
-special configuration, but don't worry, everything is already
-pre-configured
-for you, and the module is already [included](extra-builtin-modules)
+"AdvAgg":http://drupal.org/project/advagg module. This module requires
+special configuration, but don't worry, everything is already pre-configured
+for you, and the module is already "included":extra-builtin-modules
in every Drupal 6 and Drupal 7 platform. It is enough to simply enable
all its sub-modules. There are a few of them; it is not a single module.
-### Caution
+h3. Caution
-#### Enabling AdvAgg Slows Down My Site!
+h4. Enabling AdvAgg Slows Down My Site!
If you enable AdvAgg, requests and page views will suddenly take more
time to process. Don't worry. This is a normal, one-time event, as
AdvAgg generates the initial aggregated files.
We recommend that you also enable
-the [HTTPRL](http://drupal.org/project/httprl) module, which is also
-[included](extra-builtin-modules). It will improve
+the "HTTPRL":http://drupal.org/project/httprl module, which is also "included":extra-builtin-modules. It will improve
the performance of AdvAgg.
-#### My CSS/Javascript Files Won't Update!
+h4. My CSS/Javascript Files Won't Update!
If you enable AdvAgg, your site will begin to aggregate CSS and
Javascript files using the advanced aggregation. When you edit
the CSS or Javascript source files, you will need to rebuild some of
the aggregated bundles to see your changes.
-However, you no longer need to use the old `Clear cached data` button
-on the Performance page for this purpose. (In fact, it won't do
-anything.)
+However, you no longer need to use the old @Clear cached data@ button
+on the Performance page for this purpose. (In fact, it won't do anything.)
-Instead, use the smart `Flush AdvAgg Cache` button at
-`admin/settings/advagg`. This will intelligently rebuild only the
-aggregated
-bundles which include the modified file, and you'll be able to see your
-changes.
+Instead, use the smart @Flush AdvAgg Cache@ button at
+@admin/settings/advagg@. This will intelligently rebuild only the aggregated
+bundles which include the modified file, and you'll be able to see your changes.
Since the filenames of the aggregated bundles do not change, the layout
will not break when you rebuild them.
-More Information
-----------------
+h2. More Information
-### Without AdvAgg, Why Does Clearing the Caches Break the Layout?
+h3. Without AdvAgg, Why Does Clearing the Caches Break the Layout?
-Without AdvAgg, CSS and Javascript files are normally *aggregated*
+Without AdvAgg, CSS and Javascript files are normally _aggregated_
by Drupal default. We enable simple aggregation for you automatically.
-Files are combined into single (bundled) CSS and Javascript files with
-unique names.
+Files are combined into single (bundled) CSS and Javascript files with unique names.
-When you use the `clear cached data` button on the admin Performance
+When you use the @clear cached data@ button on the admin Performance
page, here's what happens:
-- the aggregated CSS and Javascript files are purged
-- new aggregated files are generated with new names
-- but the cached versions of the site pages still reference the *old*
- aggregated files
+* the aggregated CSS and Javascript files are purged
+* new aggregated files are generated with new names
+* but the cached versions of the site pages still reference the _old_ aggregated files
Now your site is full of old paths. As far as Drupal can tell, the CSS
and Javascript files are all missing. AdvAgg to the rescue!
diff --git a/03.managing/02.modules/boost/docs.md b/03.managing/02.modules/boost/docs.md
new file mode 100644
index 0000000..480e4e7
--- /dev/null
+++ b/03.managing/02.modules/boost/docs.md
@@ -0,0 +1,75 @@
+---
+title: TITLE
+slug: URI
+menu: MENU
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+routes:
+ aliases:
+ - /URI
+---
+
+Using the Boost Module for Caching
+
+The "Boost":https://drupal.org/project/boost module caches full pages
+for *anonymous* visitors only. On our hosting, Boost can be used in
+conjuction with other caching systems such as "Speed Booster":cache-speed-booster
+and "Redis.":cache-redis
+
+h2. Task: Enable Boost
+
+Boost is supported in our Nginx server configuration, so you do not
+use an @.htaccess@ file or need to do any other configuration.
+
+To use Boost, simply:
+
+# *Enable* the module as usual, on the "Modules" admin page.
+
+# If this is a custom platform in the @~/static@ directory, and this is
+ the first site on the platform for which you have enabled Boost,
+ then you must also "Verify" this site in Aegir (see "Caution" below).
+
+** With our built-in platforms, you do not need this extra step.
+
+h2. Task: Disable Boost
+
+You can disable Boost like any other module, on the "Modules" admin page.
+
+To disable Boost for a particular URL on the fly, add @?nocache=1@.
+This will also disable "Speed Boost":cache-speed-booster for that URL.
+
+h2. Caution
+
+h3. Boost Needs a "cache/" Directory
+
+Boost requires a @cache/@ directory in the platform.
+
+
+(Example: ~/static/my-platform-01/cache/)
+
+
+This directory is automatically included on all
+our "built-in platforms":built-in-platforms.
+
+If you "add a custom platform":add-custom-platform, you can also trigger
+the creation of this directory with correct permissions with these steps:
+
+# Enable the Boost module for one of the sites on this platform.
+
+# Run the "Verify" task on this site.
+
+It is important that you use Aegir to create this directory in your
+custom platform. You shouldn't create it via FTPS, SFTP, or on the command
+line. If the directory has been copied during the site import procedure,
+you should delete and re-create it via Aegir, as explained above.
+
+h2. References
+
+* "Using Speed Booster Caching":cache-speed-booster
+
+* "How to Disable All Caching":cache-disable-all
+
+* "How to Disable CSS and Javascript Caching":cache-disable-css-js
diff --git a/03.managing/02.modules/chapter.md b/03.managing/02.modules/chapter.md
new file mode 100644
index 0000000..bca560c
--- /dev/null
+++ b/03.managing/02.modules/chapter.md
@@ -0,0 +1,15 @@
+---
+title: Drupal Modules on BOA
+menu: Modules on BOA
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+---
+
+### Chapter 3.2
+
+# Drupal Modules on BOA
+
+Learn useful details which will make managing Drupal sites with Aegir easier.
diff --git a/03.managing/02.modules/extra-builtin-modules/docs.md b/03.managing/02.modules/extra-builtin-modules/docs.md
new file mode 100644
index 0000000..77b831e
--- /dev/null
+++ b/03.managing/02.modules/extra-builtin-modules/docs.md
@@ -0,0 +1,243 @@
+---
+title: TITLE
+slug: URI
+menu: MENU
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+routes:
+ aliases:
+ - /URI
+---
+
+Extra Built-In Modules on All Aegir Platforms
+
+Every Aegir 6.x and 7.x platform includes certain extra built-in
+modules. Some are enabled by default, others are only supported, and a
+few are disabled. On this page, you'll find a complete listing of
+these modules for the latest stable "BOA":boa release. You'll also
+find more information about working with these modules on your Aegir
+sites and "platforms":platform.
+
+h2. Supported, Enabled, Disabled: Complete List
+
+This list of built-in modules is updated with each stable "BOA" release.
+
+h3. What do the Symbols Mean?
+
+* @[S]@ *Supported*: This module may require custom rewrites on the web
+ server level. Since you cannot do this with an @.htaccess@ file on
+ an Nginx server, we have added all required rewrites and
+ configuration at the system level. Note: not all supported modules
+ are actually bundled in the platforms; if the list does not include
+ a @[B]@ for a module, you need to download it. Often, the module
+ listed as supported needs some pre-configuration on the @settings.php@
+ file level, so "BOA":boa comes with these settings pre-configured
+ in the @global.inc@ file. You can't access or edit this file, but it is
+ included in every site's @settings.php@ automatically.
+
+* @[B]@ *Bundled*: The code for this module is included in the
+ platform. You don't need to download it; you can simply enable
+ it. (All bundled modules are supported, but not all supported modules
+ are bundled.)
+
+* @[SE]@ *Soft Enabled*: This module is enabled when you @Create@ a
+ "blank" site with Aegir, but if you disable it, the daily
+ maintenance monitor will not turn it back on.
+
+* @[FE]@ *Force Enabled*: If you disable this module, the daily monitor
+ will enable it again.
+
+* @[FD]@ *Force Disabled*: If you enable this module, the daily
+ monitor will disable it again. (For instance, you can temporarily
+ enable the @devel@ or @dblog@ module while you're developing a site,
+ but if you forget to disable it, it'll get disabled automatically.)
+
+* @[NA]@ *Special Modules*: This module is used without the need
+ to enable it.
+
+* @[D6]@ Included and/or Supported on *Drupal 6* platforms
+
+* @[D7]@ Included and/or Supported on *Drupal 7* platforms
+
+h3. Contrib Modules [S]upported:
+
+
+ ais ------------------------ [D7] ------ [S]
+ audio ---------------------- [D6] ------ [S]
+ backup_migrate ------------- [D6,D7] --- [S]
+ ckeditor ------------------- [D6,D7] --- [S]
+ fbconnect ------------------ [D6,D7] --- [S]
+ fckeditor ------------------ [D6] ------ [S]
+ imagecache ----------------- [D6,D7] --- [S]
+ imagecache_external -------- [D6,D7] --- [S]
+ responsive_images ---------- [D7] ------ [S]
+ tinybrowser ---------------- [D6,D7] --- [S]
+ tinymce -------------------- [D6] ------ [S]
+ wysiwyg_spellcheck --------- [D6,D7] --- [S]
+
+
+h3. Contrib Modules [S]upported & [B]undled:
+
+
+ advagg --------------------- [D6,D7] --- [S] [B]
+ blockcache_alter ----------- [D6,D7] --- [S] [B]
+ boost ---------------------- [D6,D7] --- [S] [B]
+ cdn ------------------------ [D6,D7] --- [S] [B]
+ config_perms --------------- [D6,D7] --- [S] [B]
+ css_emimage ---------------- [D6,D7] --- [S] [B]
+ dbtuner -------------------- [D6] ------ [S] [B]
+ esi ------------------------ [D6,D7] --- [S] [B]
+ expire --------------------- [D6,D7] --- [S] [B]
+ filefield_nginx_progress --- [D6,D7] --- [S] [B]
+ flood_control -------------- [D7] ------ [S] [B]
+ force_password_change ------ [D6,D7] --- [S] [B]
+ fpa ------------------------ [D6,D7] --- [S] [B]
+ httprl --------------------- [D6,D7] --- [S] [B]
+ login_security ------------- [D6,D7] --- [S] [B]
+ nocurrent_pass ------------- [D7] ------ [S] [B]
+ phpass --------------------- [D6] ------ [S] [B]
+ private_upload ------------- [D6] ------ [S] [B]
+ purge ---------------------- [D6,D7] --- [S] [B]
+ readonlymode --------------- [D6,D7] --- [S] [B]
+ reroute_email -------------- [D6,D7] --- [S] [B]
+ securesite ----------------- [D6,D7] --- [S] [B]
+ security_review ------------ [D6,D7] --- [S] [B]
+ site_verify ---------------- [D6,D7] --- [S] [B]
+ speedy --------------------- [D7] ------ [S] [B]
+ taxonomy_edge -------------- [D6,D7] --- [S] [B]
+ textile -------------------- [D6,D7] --- [S] [B]
+ variable_clean ------------- [D6,D7] --- [S] [B]
+ vars ----------------------- [D7] ------ [S] [B]
+ views_content_cache -------- [D6,D7] --- [S] [B]
+ views404 ------------------- [D6,D7] --- [S] [B]
+
+
+h3. Contrib Modules [S]upported & [B]undled & [F]orce[E]nabled:
+
+
+ entitycache ---------------- [D7] ------ [S] [B] [FE]
+ robotstxt ------------------ [D6,D7] --- [S] [B] [FE]
+
+
+h3. Special [NA] Contrib Modules [S]upported & [B]undled:
+
+
+ cache_backport ------------- [D6] ------ [S] [B] [NA]
+ redis ---------------------- [D6,D7] --- [S] [B] [NA]
+
+
+h3. Contrib Themes [S]upported & [B]undled & [S]oft[E]nabled:
+
+
+ admin ---------------------- [D6,D7] --- [S] [B] [SE]
+ rubik ---------------------- [D6,D7] --- [S] [B] [SE]
+
+
+h3. Contrib Modules [F]orce[D]isabled:
+
+
+ css_gzip ------------------- [D6] -------------- [FD]
+ devel ---------------------- [D6,D7] ----------- [FD]
+ performance ---------------- [D6,D7] ----------- [FD]
+ javascript_aggregator ------ [D6] -------------- [FD]
+ l10n_update ---------------- [D6,D7] ----------- [FD]
+ poormanscron --------------- [D6] -------------- [FD]
+ supercron ------------------ [D6] -------------- [FD]
+
+
+h3. Core Modules [F]orce[D]isabled:
+
+
+ cookie_cache_bypass -------- [D6] -------------- [FD]
+ dblog ---------------------- [D6,D7] ----------- [FD]
+ syslog --------------------- [D6,D7] ----------- [FD]
+ update --------------------- [D6,D7] ----------- [FD]
+
+
+h3. Core Modules [F]orce[E]nabled:
+
+
+ path_alias_cache ----------- [D6] -------------- [FE]
+
+
+h3. Drush Extensions [S]upported & [B]undled
+
+Drush Extensions:
+
+ clean_missing_modules ------ [D6,D7] --- [S] [B]
+ drush_ecl ------------------ [D7] ------ [S] [B]
+ drush_make ----------------- [D6,D7] --- [S] [B]
+ registry_rebuild ----------- [D6,D7] --- [S] [B]
+
+
+h2. More Information
+
+h3. Do These Modules Get Added to Your Custom Platforms?
+
+*Yes*, these modules will get automatically added to your custom
+ platform in @~/static/@, but only if:
+
+# You *add at least one site* to your custom platform,
+
+# then *wait a day* for the maintenance monitor to run,
+
+# then *run @Verify@* on the custom platform, to
+ "keep Aegir informed":keeping-aegir-informed about the new modules.
+ If you skip this last step, Aegir will not know about the new modules.
+
+Read more about "adding a custom platform":add-custom-platform to @~/static/@.
+
+It's probably a good idea to create blank site whenever you add a
+custom platform, so that you'll get these modules as soon as possible.
+
+h3. Where Are Modules Added to Custom Platforms?
+
+These "built-in" modules are added to your custom platforms using
+_symbolic links_, or _symlinks_.
+
+You won't see these symlinks in the @sites/@ directory. Instead,
+they're in a subdirectory of the platform root.
+
+For 6.x platforms, the extra modules are symlinked in
+@modules/o_contrib/@.
+
+For 7.x platforms, the extra modules are symlinked in
+@modules/o_contrib_seven/@.
+
+Your SSH user can't @cd@ to these directories. If you try, you'll get
+a warning.
+
+h3. How Can You Override Built-In Modules?
+
+Overriding built-in modules is easy. Drupal already has logic for
+overriding modules depending on the filesystem location. Before looking
+in the platform root, Drupal will look for each module in:
+
+- @sites/foo.com/modules/@, the site-specific directory, and then
+- @sites/all/modules/@, the platform-wide directory
+
+To override the built-in platform version of a particular module,
+place your copy in either location.
+
+We strongly recommend that you
+place *all contrib modules into @sites/all/modules/@*,
+and *never into @sites/foo.com/modules@*. Even
+if you'll only use the module on one site, the platform-wide
+@sites/all/modules@ offers excellent Aegir support for future
+upgrades.
+
+By contrast, putting modules into the site-specific
+@sites/foo.com/modules/@ can cause serious problems and even
+breakage. The site-specific directory is best saved for custom,
+one-off modules that you develop specifically for that site.
+
+Read more about "always placing contrib modules into @sites/all/modules@.":sites-all-modules
+
+[boa]
+[platform]
+[add-custom-platform]
+[keeping-aegir-informed]
+[sites-all-modules]
diff --git a/03.managing/02.modules/modules-enabled-disabled/docs.md b/03.managing/02.modules/modules-enabled-disabled/docs.md
new file mode 100644
index 0000000..cb85b74
--- /dev/null
+++ b/03.managing/02.modules/modules-enabled-disabled/docs.md
@@ -0,0 +1,95 @@
+---
+title: TITLE
+slug: URI
+menu: MENU
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+routes:
+ aliases:
+ - /URI
+---
+
+Modules Enabled or Disabled Automatically
+
+Every morning on your Aegir instance, a daily maintenance monitor
+enables some modules and disables others. You can consult the
+"complete list of built-in modules":extra-builtin-modules,
+but this doc covers the key modules that get turned on or off.
+
+h2. Key Modules That Get Enabled
+
+Every morning (in the timezone for your Aegir server), these modules
+get *enabled*:
+
+* "Path alias cache":http://pressflow.org (D6 only)
+* "RobotsTxt":https://drupal.org/project/robotstxt (D6 and D7).
+
+h2. Key Modules That Get Disabled
+
+Every morning (in the timezone for your Aegir server), these modules
+get *disabled*:
+
+* "Background Process":https://drupal.org/project/background_process,
+* "Cookie Cache Bypass Advanced":https://drupal.org/project/cookie_cache_bypass_adv
+* DBlog (core)
+* Syslog (core)
+* "Devel":https://drupal.org/project/devel,
+* "Javascript Aggregator":https://drupal.org/project/javascript_aggregator
+* "Localization Update":https://drupal.org/project/l10n_update,
+* "Poormanscron":https://drupal.org/project/poormanscron,
+* "SuperCron":https://drupal.org/project/supercron,
+* "Ultimate Cron":https://drupal.org/project/ultimate_cron,
+* Update (core)
+
+* "Boost Crawler":https://drupal.org/project/boost - this Boost's submodule feature
+ is disabled on the fly, permanently, so it is not affected by the explained
+ above automated maintenance workflow, but still should be listed here.
+
+These modules should never be used on a live site. They either aren't
+appropriate for a high performance system, or they aren't allowed for
+performance reasons.
+
+Again, for a full list of disabled modules, consult the
+"complete list of built-in modules":extra-builtin-modules
+
+h2. More Information
+
+h3. Modules to Avoid?
+
+Even though it is not actually disabled,
+you should avoid the "Search 404":https://drupal.org/project/search404
+module.
+
+h3. What About DBlog or Devel for Development?
+
+Although DBlog and Devel are disabled each morning, they can be useful
+for temporary debugging. You can enable and use these modules as
+usual. But they'll be disabled in the morning.
+
+h4. DBlog Data Stays Intact
+
+Although DBlog gets disabled, the data collected in the @watchdog@
+table remains intact. To access this data easily, enable DBlog again.
+
+h4. Beware dpm() and dpr()
+
+If you use Devel to debug a module, be very careful about adding
+@dpm()@ or @dpr()@ calls to your code. These functions depend on
+Devel, and they're extremely useful, but you must delete them when
+you're done debugging. If you forget to delete them before Devel gets
+disabled, your code will break, and probably take down your site.
+
+h4. Prevent Module Disabling
+
+To avoid having these modules disabled, include @.devel.@ or @.dev.@ in
+the *main domain name*. Adding an alias is not enough. To keep these
+modules enabled, the @.devel.@ or @.dev.@ must be included in the main
+domain.
+
+
+h2. References
+
+"Extra Built-In Modules on All Aegir Platforms":extra-builtin-modules
diff --git a/03.managing/02.modules/override-module-aegir/docs.md b/03.managing/02.modules/override-module-aegir/docs.md
new file mode 100644
index 0000000..8f74a62
--- /dev/null
+++ b/03.managing/02.modules/override-module-aegir/docs.md
@@ -0,0 +1,105 @@
+---
+title: TITLE
+slug: URI
+menu: MENU
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+routes:
+ aliases:
+ - /URI
+---
+
+You can also _override_
+existing modules and themes with a new version.
+
+h2. Overview: _Override_ a Module or Theme
+
+You can _override_ or module or theme that's already in the platform.
+For instance, you can upload a newer or development version. Drupal
+will use the version you have uploaded.
+
+You can override for the entire platform (@sites/all/modules@) or for
+one site (@sites/foo.com/modules@).
+
+Drupal decides which version of a module or theme to run based on its
+location in the filesystem. The order of precedence is:
+
+# @sites/foo.com/modules/@
+# @sites/all/modules@
+# the platform @modules/@ directory
+# the platform @profiles/foo/modules@ directory
+
+ *Caution:* Overriding the wrong module or theme can *break all the
+sites on your platform*. In general, instead of upgrading, you should
+prepare a new platorm, and "migrate each site to the new platform":migrate-platform.
+Please read the "Caution" section below before deciding to override.
+
+h2. Step-by-Step: _Override a Module or Theme for a Platform_
+
+*Caution*: You should almost never override a module for an entire platform.
+But if you insist, here's how.
+
+# Upload your module or theme to @sites/all/modules/@ or @sites/all/themes/@ on the platform.
+
+# Within @sites/all/modules/@ or @sites/all/themes/@, run @chmod -R 775@ to set correct permissions.
+
+# For each site on the platform, rebuild the registry with @drush rr@ or the @Rebuild registry@ Aegir task.
+
+# For each site on the platform, run the @Backup@ Aegir task.
+
+# For each site on the platform, apply any necessary database updates. Use @drush dbup@ or browse to @http:/foo.com/update.php@
+
+h2. Step-by-Step: _Override_ a Module or Theme for One Site
+
+Overriding a module for one site is still dangerous, but at least you can quickly test it first on a copy.
+
+# Make a test copy of your live site with the @Clone@ task in Aegir. Example: @bar.dev.foo.com@
+
+# Upload your module or theme to the site-specific directory *of the test site*. Example: @sites/bar.dev.foo.com/modules/@
+
+# Within this directory, run @chmod -R 775@ to set correct permissions.
+
+# Rebuild the registry with @drush rr@ or the @Rebuild registry@ Aegir task for the site.
+
+# In Aegir, run the @Backup@ task for the test site.
+
+# Apply any module updates. Use @drush dbup@ or browse to
+ @http://bar.dev.foo.com/update.php@.
+
+# Inspect the test site. If nothing has broken, delete the test site,
+ and repeat these steps for your live site.
+
+h2. Caution
+
+
+h3. Don't Override an "Older" Module Without Research
+
+Sometimes the built-in platforms seem to have "outdated" modules.
+Don't assume a lazy maintainer! The newer version might have an
+incompatibility or a bug that would bring down all the sites on the
+platform. Research carefully before deciding to override.
+
+h3. Never Hack Core!
+
+Although you can override modules, you can't override core. If you
+want to patch core, you'll need to
+"build your own custom platform.":custom-platform
+(Please don't request that we patch core on a built-in platform.)
+
+But you've heard the saying, right? "_Never hack core!_":never-hack-core
+We strongly encourage you to avoid patching core, even on your own custom platform.
+
+In fact, the core we offer on our built-in platforms has _already_ had
+important patches and improvements applied. We optimize core for our
+hosting.
+
+If you choose to build your own platforms, we suggest you use the same
+core that we offer with our built-in platforms.
+We publish our customized cores at our "Omega8cc GitHub
+account":https://github.com/omega8cc/:
+
+* "Drupal 7":https://github.com/omega8cc/7x/ from Omega8cc
+* "Pressflow (Drupal 6)":https://github.com/omega8cc/pressflow6/ from Omega8cc
diff --git a/03.managing/modules/print-pdf-wkhtmltopdf/docs.md b/03.managing/02.modules/print-pdf-wkhtmltopdf/docs.md
similarity index 53%
rename from 03.managing/modules/print-pdf-wkhtmltopdf/docs.md
rename to 03.managing/02.modules/print-pdf-wkhtmltopdf/docs.md
index e9f9bc6..2a9d968 100644
--- a/03.managing/modules/print-pdf-wkhtmltopdf/docs.md
+++ b/03.managing/02.modules/print-pdf-wkhtmltopdf/docs.md
@@ -11,34 +11,30 @@ routes:
aliases:
- /URI
---
+
Print PDFs With "wkhtmltopdf"
There are several Drupal modules that let you print a Drupal page as a
PDF. These modules may require a third-party "wkhtmltopdf" binary.
The BOA system provides this binary, available at the standard
-system path: `/usr/bin/wkhtmltopdf`.
+system path: @/usr/bin/wkhtmltopdf@.
-Problem: Module Can't Find "wkhtmltopdf"
-----------------------------------------
+h2. Problem: Module Can't Find "wkhtmltopdf"
-Some modules will not recognize `wkhtmltopdf` at
-`/usr/bin/wkhtmltopdf`. They may suggest that you instead upload
-`wkhtmltopdf`
-into one of the `libraries/` or `modules/` trees, or that you symlink
-the system level binary in these directories. Neither of these
-suggestions are correct
-or applicable in the BOA system, and these modules will still refuse to
-work.
+Some modules will not recognize @wkhtmltopdf@ at
+@/usr/bin/wkhtmltopdf@. They may suggest that you instead upload @wkhtmltopdf@
+into one of the @libraries/@ or @modules/@ trees, or that you symlink
+the system level binary in these directories. Neither of these suggestions are correct
+or applicable in the BOA system, and these modules will still refuse to work.
-Solution: Patch Your Module
----------------------------
+h2. Solution: Patch Your Module
We recommend that you patch your module to use the
-correct system level binary at `/usr/bin/wkhtmltopdf`. The patch
-should be trivial: see [this patch](wkhtmltopdf-patch) for reference.
+correct system level binary at @/usr/bin/wkhtmltopdf@. The patch
+should be trivial: see "this patch":wkhtmltopdf-patch for reference.
If you have never patched a module, see
-[this tutorial on drupal.org.](drupal-patch)
+"this tutorial on drupal.org.":drupal-patch
[wkhtmltopdf]http://code.google.com/p/wkhtmltopdf/downloads/list
diff --git a/03.managing/modules/robots-txt/docs.md b/03.managing/02.modules/robots-txt/docs.md
similarity index 52%
rename from 03.managing/modules/robots-txt/docs.md
rename to 03.managing/02.modules/robots-txt/docs.md
index 8d3e3cd..daebdc6 100644
--- a/03.managing/modules/robots-txt/docs.md
+++ b/03.managing/02.modules/robots-txt/docs.md
@@ -11,89 +11,73 @@ routes:
aliases:
- /URI
---
+
How to Use robots.txt on Aegir
-Aegir, being based on the Drupal Multisite feature, requires that every
-site
+Aegir, being based on the Drupal Multisite feature, requires that every site
has its own copy of the "robots.txt" file. You can't use a single,
-central "robots.txt" file in the platform root directory, because it
-would be
+central "robots.txt" file in the platform root directory, because it would be
shared across all sites on the same platform.
-Problem: You need to customize "robots.txt" per site
-----------------------------------------------------
+h2. Problem: You need to customize "robots.txt" per site
-The BOA system enables "robots.txt" support for every hosted site, but
-it comes
-with the contents of the default Drupal "robots.txt" file. If your
-Drupal site
+The BOA system enables "robots.txt" support for every hosted site, but it comes
+with the contents of the default Drupal "robots.txt" file. If your Drupal site
on Aegir needs a custom "robots.txt" file, you can't put
-"robots.txt" in the root of your platform directory, because the BOA
-system
+"robots.txt" in the root of your platform directory, because the BOA system
will delete it, to meet requirements of supported RobotsTxt module.
-Solution 1: RobotsTxt Module
-----------------------------
+h2. Solution 1: RobotsTxt Module
-Use the [RobotsTxt](http://drupal.org/project/robotstxt) module. With
-RobotsTxt, you can configure `robots.txt` for each site separately.
+Use the "RobotsTxt":http://drupal.org/project/robotstxt module. With
+RobotsTxt, you can configure @robots.txt@ for each site separately.
-Drupal 6: `admin/settings/robotstxt`
+Drupal 6: @admin/settings/robotstxt@
-Drupal 7: `admin/config/search/robotstxt`
+Drupal 7: @admin/config/search/robotstxt@
You don't need to download RobotsTxt. This module is on the
-[list of modules that come bundled](supported-enabled-disabled) on all
-BOA
-[built-in platforms,](built-in-platforms). RobotsTxt is enabled by
-default.
+"list of modules that come bundled":supported-enabled-disabled on all BOA
+"built-in platforms,":built-in-platforms. RobotsTxt is enabled by default.
-Solution 2: Put "robots.txt" in "files/"
-----------------------------------------
+h2. Solution 2: Put "robots.txt" in "files/"
The downside to RobotsTxt is that, even with caching, the bots are
still hitting Drupal.
-For better performance, upload a separate, unique `robots.txt` file to
-the `files/` directory for any site.
+For better performance, upload a separate, unique @robots.txt@ file to
+the @files/@ directory for any site.
-For instance, for `foo.com`, you want `/sites/foo.com/files/robots.txt`.
+For instance, for @foo.com@, you want @/sites/foo.com/files/robots.txt@.
-Thanks to our built-in Nginx rewrites, a `robots.txt` at this location
+Thanks to our built-in Nginx rewrites, a @robots.txt@ at this location
will take precedence over the RobotsTxt module for that site.
-Automatically generated "robots.txt"
-------------------------------------
+h2. Automatically generated "robots.txt"
Starting with BOA-2.0.10, the system will generate this static file
automatically for every active site. This means that if you make
any changes in the RobotsTxt module configuration, they will not be
-active until you delete the existing `/sites/foo.com/files/robots.txt`
+active until you delete the existing @/sites/foo.com/files/robots.txt@
static file. This will allow the system to regenerate it from updated
settings.
-Domain Access compatibility
----------------------------
+h2. Domain Access compatibility
-Starting with BOA-2.0.10, our built-in Nginx rewrites support
-additional,
-per-domain "robots.txt" files located in the same
-`/sites/foo.com/files/`
+Starting with BOA-2.0.10, our built-in Nginx rewrites support additional,
+per-domain "robots.txt" files located in the same @/sites/foo.com/files/@
directory. These extra files can't be generated automatically, and they
are also completely independent from RobotsTxt module. These files must
be created and managed mnaually.
They should follow this naming convention:
-`/sites/foo.com/files/foo.com.robots.txt`
-`/sites/foo.com/files/bar.com.robots.txt`
+@/sites/foo.com/files/foo.com.robots.txt@
+@/sites/foo.com/files/bar.com.robots.txt@
-Nginx will try to find the file that matches the currently requested
-domain.
-For example, it will automatically map a `http://foo.com/robots.txt`
-request
-to the file `/sites/foo.com/files/foo.com.robots.txt` (if this file
-exists).
+Nginx will try to find the file that matches the currently requested domain.
+For example, it will automatically map a @http://foo.com/robots.txt@ request
+to the file @/sites/foo.com/files/foo.com.robots.txt@ (if this file exists).
[add-custom-platform]:link
diff --git a/03.managing/why-use-built-in-platforms/docs.md b/03.managing/03.why-use-built-in-platforms/docs.md
similarity index 58%
rename from 03.managing/why-use-built-in-platforms/docs.md
rename to 03.managing/03.why-use-built-in-platforms/docs.md
index c9c7942..120f468 100644
--- a/03.managing/why-use-built-in-platforms/docs.md
+++ b/03.managing/03.why-use-built-in-platforms/docs.md
@@ -11,53 +11,48 @@ routes:
aliases:
- /URI
---
+
When to Use Our Built-In Aegir Platforms
-Problem: Should You Use Built-in Aegir Platforms?
--------------------------------------------------
+h2. Problem: Should You Use Built-in Aegir Platforms?
-You can either [add a custom platform](add-custom-platform) to Aegir or
-use one of our [built-in platforms](built-in-platforms). Which should
+You can either "add a custom platform":add-custom-platform to Aegir or
+use one of our "built-in platforms":built-in-platforms. Which should
you choose?
-Solution: Consider the Needs of the Site
-----------------------------------------
+h2. Solution: Consider the Needs of the Site
The answer depends on the particular site.
-### When to Make a Custom Platform
+h3. When to Make a Custom Platform
A custom platform makes sense if:
-- You want to use a "distribution" that isn't included
- in the [list of built-in platforms.](built-in-platforms)
+* You want to use a "distribution" that isn't included
+ in the "list of built-in platforms.":built-in-platforms
-- You want to use a module that is incompatible with the other modules
- on the built-in platorms.
+* You want to use a module that is incompatible with the other modules on the built-in platorms.
-- You need to patch core.
+* You need to patch core.
-### When to Use a Built-in Platform
+h3. When to Use a Built-in Platform
If your site does not fit any of those conditions, consider one of our
-[built-in platfroms](built-in-platforms).
+"built-in platfroms":built-in-platforms.
Built-in platforms offer two major advantages over custom platforms:
-- Built-in platforms run on **faster hardware**.
+* Built-in platforms run on *faster hardware*.
-- Built-in platforms feature carefully chosen, patched, and
- maintained
- **modules**. You can customize these platforms by adding further
- *modules and themes.
+* Built-in platforms feature carefully chosen, patched, and maintained
+ *modules*. You can customize these platforms by adding further
+ *modules and themes.
-More Information
-----------------
+h2. More Information
-### Fast SSD Drives
+h3. Fast SSD Drives
-Our Omega8.cc [hybrid storage](hybrid-storage) system relies on quality
-SSD
+Our Omega8.cc "hybrid storage":hybrid-storage system relies on quality SSD
(Solid State Drive) technology to serve up your web sites with blazing
speed. But we know you also need plenty of affordable space for your
files. When you upload files, they go onto the bigger, but also
@@ -67,10 +62,10 @@ These SAS drives are professional grade, with far more speed and
quality than the cheap and slow SATA (Serial ATA) drives which are so
common among webhosts. But even with SAS, SSD is still faster.
-**All our built-in platforms are on these faster SSD drives.** But
+*All our built-in platforms are on these faster SSD drives.* But
when you add a custom platform, it goes on the slower SAS drive.
-### Patched and Curated Modules
+h3. Patched and Curated Modules
Our built-in platforms offer a carefully selected group of modules
that should work cleanly together. You know that these particular
@@ -79,15 +74,15 @@ modules, with these particular versions, will function well.
Many of the modules, and even parts of core, also include important
patches. Sometimes, when a security release comes out for Drupal, we
can fix the problem on our platforms by patching core. With our patch,
-you don't need to [migrate to an updated platform](migrate-platform).
+you don't need to "migrate to an updated platform":migrate-platform.
-### You Can Customize Our Built-In Platforms
+h3. You Can Customize Our Built-In Platforms
We know you'll want to add your own modules for your unique sites. No
-problem. You can [customize our built-in
-platforms](customize-built-in-platform)
+problem. You can "customize our built-in platforms":customize-built-in-platform
by adding modules and themes.
+
[hybrid-storage]http://omega8.cc/hybrid-storage-high-speed-big-space-237
[extra-modules-available]http://omega8.cc/extra-modules-available-in-all-platforms-123
diff --git a/03.managing/customize-built-in-platforms/docs.md b/03.managing/04.customize-built-in-platforms/docs.md
similarity index 52%
rename from 03.managing/customize-built-in-platforms/docs.md
rename to 03.managing/04.customize-built-in-platforms/docs.md
index 2362c05..0f920d1 100644
--- a/03.managing/customize-built-in-platforms/docs.md
+++ b/03.managing/04.customize-built-in-platforms/docs.md
@@ -11,42 +11,37 @@ routes:
aliases:
- /URI
---
+
Add a Module or Theme to a Built-in Platform
When you create a new Drupal site on Aegir, you get a choice of many
-[built-in platforms](built-in-platforms). Each platform offers a
+"built-in platforms":built-in-platforms. Each platform offers a
particular collection of useful modules. But you can add modules and
themes to these built-in platforms.
Once you add a module or theme to your platform, you can enable it for
any site on the platform.
-Task: Add a Module or Theme to a Platform
------------------------------------------
+h2. Task: Add a Module or Theme to a Platform
-1. Upload your module or theme to `sites/all/modules/` or
- `sites/all/themes/` on the platform.
+# Upload your module or theme to @sites/all/modules/@ or @sites/all/themes/@ on the platform.
-1. Within `sites/all/modules/` or `sites/all/themes/`, run
- `chmod -R 775` to set correct permissions.
+# Within @sites/all/modules/@ or @sites/all/themes/@, run @chmod -R 775@ to set correct permissions.
-1. In Aegir, run `Verify` on this platform.
+# In Aegir, run @Verify@ on this platform.
-1. For each site on the platform, rebuild the registry with `drush rr`
- or the `Rebuild registry` Aegir task.
+# For each site on the platform, rebuild the registry with @drush rr@ or the @Rebuild registry@ Aegir task.
-1. Enable the module on the site(s) where you want to use it. For each
- site, you may wish to test the new module on a clone first.
+# Enable the module on the site(s) where you want to use it. For each
+ site, you may wish to test the new module on a clone first.
-References
-----------
+h2. References
-[Add a Module or Theme to a Site on Aegir](add-module-site)
+"Add a Module or Theme to a Site on Aegir":add-module-site
-[Override a Module or Theme on Aegir](override-module)
+"Override a Module or Theme on Aegir":override-module
-[Customize Our Built-in Platforms Instead of Adding Custom
-Platforms.](link)
+"Customize Our Built-in Platforms Instead of Adding Custom Platforms.":link
[hybrid-storage]http://omega8.cc/hybrid-storage-high-speed-big-space-237
diff --git a/03.managing/add-custom-platform-properly/docs.md b/03.managing/add-custom-platform-properly/docs.md
index c24857f..b7b37b3 100644
--- a/03.managing/add-custom-platform-properly/docs.md
+++ b/03.managing/add-custom-platform-properly/docs.md
@@ -11,107 +11,101 @@ routes:
aliases:
- /URI
---
+
How to Add Your Custom Platforms to Aegir
-**Before you begin:** This doc explains how to add your own custom
-[platform](platform) to Aegir. But first, we suggest that you look at
-our many [built-in platforms](built-in-platforms). Our
-built-in-platforms are [easy to customize](customize-built-in), and
+*Before you begin:* This doc explains how to add your own custom
+"platform":platform to Aegir. But first, we suggest that you look at
+our many "built-in platforms":built-in-platforms. Our
+built-in-platforms are "easy to customize":customize-built-in, and
will always run a little faster than any custom platforms you upload.
However, if you want to build a custom platform on Aegir, here's how.
-Task: Add a Custom Platform to Aegir
-------------------------------------
+h2. Task: Add a Custom Platform to Aegir
-Step-by-Step: Add a Custom Platform to Aegir
---------------------------------------------
+h2. Step-by-Step: Add a Custom Platform to Aegir
-### Step 1: Put your custom platform files into `~/static`
+h3. Step 1: Put your custom platform files into @~/static@
Always create your custom platform in a new directory within the
-`~/static/` directory tree. If your platform root directory is `foo`,
-we suggest `~/static/platforms/foo`.
+@~/static/@ directory tree. If your platform root directory is @foo@,
+we suggest @~/static/platforms/foo@.
-You have various options for copying your platform files into this
-directory:
+You have various options for copying your platform files into this directory:
-- Upload the files with a tool like FTPS/SFTP or `rsync` over SSH.
+* Upload the files with a tool like FTPS/SFTP or @rsync@ over SSH.
-- Use a Drush [makefile](makefile). For example:
+* Use a Drush "makefile":makefile. For example:
-`drush make ~/static/makefiles/foo.make ~/static/platforms/foo`
+@drush make ~/static/makefiles/foo.make ~/static/platforms/foo@
If you upload files from an existing platform, make sure to *remove
any files for individual sites*. If Aegir discovers any sites in the
-`sites` directory, it will attempt to add them, fail, and cause
+@sites@ directory, it will attempt to add them, fail, and cause
problems for you later.
If this happens, delete the platform node in Aegir. This will also
-delete all the failed site nodes. Remove all sites from the `sites/`
+delete all the failed site nodes. Remove all sites from the @sites/@
directory, and try again.
-### Step 2: Give your platform files the correct permissions
+h3. Step 2: Give your platform files the correct permissions
Both the platform's root directory (such as
-`~/static/platforms/foo`) and its `sites/` subdirectory must be group
+@~/static/platforms/foo@) and its @sites/@ subdirectory must be group
writable.
-**Set these permissions with two simple commands:**
+*Set these permissions with two simple commands:*
- chmod 775 ~/static/platforms/foo
- chmod -R 775 ~/static/platforms/foo/sites
+bc. chmod 775 ~/static/platforms/foo
+chmod -R 775 ~/static/platforms/foo/sites
-You must set these permissions *before* you add the platform to Aegir
+You must set these permissions _before_ you add the platform to Aegir
in the next step. If you try to add the platform while the files have
the wrong permissions, Aegir will show warnings and it will cause
serious problems later.
-Make sure you use chmod **775**, and not 755.
+Make sure you use chmod *775*, and not 755.
-### Step 3: Get the full system path to your new platform
+h3. Step 3: Get the full system path to your new platform
Get the full system path to your new platform:
- cd ~/static/platforms/foo
- pwd
+bc. cd ~/static/platforms/foo
+pwd
Save this path for the next step.
-### Step 4: Create the Platform Within Aegir
+h3. Step 4: Create the Platform Within Aegir
-1. Log into the Aegir control panel and click "Add Platform".
+# Log into the Aegir control panel and click "Add Platform".
-1. Type in a name for your platform.
+# Type in a name for your platform.
-1. Once you type the name, Aegir will autogenerate a path
- to where the custom platform is expected to be.
+# Once you type the name, Aegir will autogenerate a path
+ to where the custom platform is expected to be.
-1. Make sure this path matches the path you got in the previous step.
- If not, click the little `edit` link
- and set this to the correct path.
+# Make sure this path matches the path you got in the previous step. If not, click the little @edit@ link
+ and set this to the correct path.
-1. Leave the "Platform Makefile" field blank (see below).
+# Leave the "Platform Makefile" field blank (see below).
-1. Save your platform.
+# Save your platform.
Done! You can now add and migrate sites to this platform.
-Caution
--------
+h2. Caution
-### Help! "drush make" Fails
+h3. Help! "drush make" Fails
-- Did you create the **parent directory** for your new platform? If
- your
- target is `~/static/platforms/foo`, you must first create the
- parent
- directory, `~/static/platforms`.
+* Did you create the *parent directory* for your new platform? If your
+target is @~/static/platforms/foo@, you must first create the parent
+directory, @~/static/platforms@.
-- Add the `-d` flag, and try again. (`drush make -d ...`) You'll get
- debugging output.
+* Add the @-d@ flag, and try again. (@drush make -d ...@) You'll get
+ debugging output.
-### Should You Let Aegir Build Your Platform?
+h3. Should You Let Aegir Build Your Platform?
When you use the "Add Platform" task in the last step, there is a
"Platform Makefile" field. If you don't want to upload the files
@@ -122,49 +116,43 @@ files, sets the permissions, and adds the platform. All in one step.
However, if the build fails in
Aegir, it can create ghost nodes, which adds an extra hassle.
-If you use `drush make` as described above, you can debug problems with
-`-d`.
+If you use @drush make@ as described above, you can debug problems with @-d@.
-### "Platform Path" vs. "Platform Makefile"
+h3. "Platform Path" vs. "Platform Makefile"
-The **Platform Path** points to the files for the platform. This path
-is
+The *Platform Path* points to the files for the platform. This path is
shown directly under the Platform name. Aegir guesses this path
automatically, but you can edit it if needed.
-The **Platform Makefile** is the *optional* path or URL to the drush
+The *Platform Makefile* is the _optional_ path or URL to the drush
makefile used to build the platform. If you follow the steps in this
doc, you will leave this field blank.
For more information, read the help text underneath "Platform
Makefile" on the "Add Platform" screen in Aegir.
-### Remove Unused Profiles in Your Drupal 7 Custom Platforms
+h3. Remove Unused Profiles in Your Drupal 7 Custom Platforms
If your Drupal 7 platform uses a non-default profile, we recommend
that, for clarity, you remove all three default profiles and leave
only your custom profile.
-### Begin With Enhanced Core
+h3. Begin With Enhanced Core
When building your custom platforms, we recommend that you
begin with the same enhanced Drupal core we use in all our built-in
-platforms. We publish our customized cores at our [Omega8cc GitHub
-account](https://github.com/omega8cc/):
-
-- [Drupal 7](https://github.com/omega8cc/7x/) from Omega8cc
-- [Pressflow (Drupal 6)](https://github.com/omega8cc/pressflow6/) from
- Omega8cc
-
-References
-----------
-
-- [Extra Modules Available in All
- Platforms](extra-modules-all-platforms)
-- [Supported, Enabled, Disabled -- a Complete
- List](supported-enabled-disabled-list)
-- [Modules enabled or disabled
- automatically](modules-enabled-disabled-automatically)
+platforms. We publish our customized cores at our "Omega8cc GitHub
+account":https://github.com/omega8cc/:
+
+* "Drupal 7":https://github.com/omega8cc/7x/ from Omega8cc
+* "Pressflow (Drupal 6)":https://github.com/omega8cc/pressflow6/ from Omega8cc
+
+h2. References
+
+* "Extra Modules Available in All Platforms":extra-modules-all-platforms
+* "Supported, Enabled, Disabled -- a Complete List":supported-enabled-disabled-list
+* "Modules enabled or disabled automatically":modules-enabled-disabled-automatically
+
[customize-built-in]http://omega8.cc/how-to-customize-built-in-platforms-252
diff --git a/03.managing/control-panel-features/chapter.md b/03.managing/control-panel-features/chapter.md
deleted file mode 100644
index a53d707..0000000
--- a/03.managing/control-panel-features/chapter.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-title: Advanced
-taxonomy:
- category: docs
----
-
-### Chapter 3
-
-# Advanced
-
-Get into the **nitty gritty** with these advanced topics
diff --git a/03.managing/control-panel-features/where-rename-task/docs.md b/03.managing/control-panel-features/where-rename-task/docs.md
deleted file mode 100644
index ccae903..0000000
--- a/03.managing/control-panel-features/where-rename-task/docs.md
+++ /dev/null
@@ -1,61 +0,0 @@
----
-title: TITLE
-slug: URI
-menu: MENU
-date: 08-08-2016
-published: true
-visible: true
-taxonomy:
- category: docs
-routes:
- aliases:
- - /URI
----
-Where Is the Rename Task?
-
-The Aegir admin panel offers a list of possible tasks, but there is no
-`Rename` task.
-
-Task: Rename Your Site's Main Domain
-------------------------------------
-
-To "rename" your site to a new main domain, **use the `Migrate` task**.
-
-Do **not** change the platform. Instead, leave the platform unchanged,
-and simply enter the new domain for your site.
-
-More Information
-----------------
-
-### Never Change the Domain and the Platform in One Step
-
-The `Migrate` tasks triggers many steps behind the scenes, so it is
-critical never to change both the domain name and the platform in one
-step. Doing so could make it impossible to run the `Backup` task and
-undo any mistakes.
-
-If you're renaming the domain, keep the site on the same platform.
-
-If you're migrating to a new platform, keep the same domain name.
-
-### "www." Prefix Requires Special Handling
-
-If you want to add or remove the "www." prefix from your domain name,
-you will
-need an extra step.
-
-First, `Migrate` the site to some other domain, like `anything.foo.com`.
-
-Then, `Migrate` from `anything.foo.com` to `www.foo.com` or `foo.com`.
-
-The reason for the extra step is that Aegir automatically creates an
-*alias* based on the main domain. The domain `foo.com` gets an alias
-of `www.foo.com`, and the domain of `www.foo.com gets an alias of
-`foo.com@. You can't change a main domain to one of its aliases
-directly.
-
-### References
-
-[How to Manage Aliases and Redirects](manage-aliases-redirects)
-
-[manage-aliases-redirects]
diff --git a/03.managing/gain-access-site/docs.md b/03.managing/gain-access-site/docs.md
index ef59ce7..f83607e 100644
--- a/03.managing/gain-access-site/docs.md
+++ b/03.managing/gain-access-site/docs.md
@@ -11,50 +11,46 @@ routes:
aliases:
- /URI
---
+
Log In Without a Password
You can log into any site on your Aegir instance without the password.
-As long as you can access your Aegir admin panel or [ssh](ssh) into
+As long as you can access your Aegir admin panel or "ssh":ssh into
your account, you can log in to a Drupal site.
-Task: Use a Login Link Instead of a Password
---------------------------------------------
+h2. Task: Use a Login Link Instead of a Password
-### Using the Aegir Admin Panel:
+h3. Using the Aegir Admin Panel:
-1. Run the "Reset password" task.
+# Run the "Reset password" task.
-1. Click the "Log in" link that appears in the upper left under the
- small home icon.
+# Click the "Log in" link that appears in the upper left under the small home icon.
-![Run the "Reset Password" task](http://cdn1.o8.io/cdn/farfuture/LVOwjX3qZOlwoyG2LLk683kduMH_q5m6ujOOP6UiZFg/mtime:1335973438/sites/omega8.cc/files/imagecache/lead-image-home/7/Fullscreen-98.jpg "Run the "Reset Password" task")
+!http://cdn1.o8.io/cdn/farfuture/LVOwjX3qZOlwoyG2LLk683kduMH_q5m6ujOOP6UiZFg/mtime:1335973438/sites/omega8.cc/files/imagecache/lead-image-home/7/Fullscreen-98.jpg(Run the "Reset Password" task)!
-### Using Drush
+h3. Using Drush
-If you `ssh` into your Aegir account, you can get the "Log in" link
-using drush.
+If you @ssh@ into your Aegir account, you can get the "Log in" link using drush.
-1. `cd` into a directory for your site. (For example, `sites/foo.com/`)
+# @cd@ into a directory for your site. (For example, @sites/foo.com/@)
-1. `drush5 uli`
+# @drush5 uli@
-1. Copy the link into your browser. This link will log you in to
- the site.
+# Copy the link into your browser. This link will log you in to the site.
-More Information
-----------------
+h2. More Information
-### So the Site Owner Doesn't Need to Send the Password?
+h3. So the Site Owner Doesn't Need to Send the Password?
-Correct. You should **never** have the site owner send you a
+Correct. You should *never* have the site owner send you a
password. Instead, use this technique to log into the site without
altering the password.
-### Can I Log In As A Particular User?
+h3. Can I Log In As A Particular User?
If you want to log in as a particular user, you can add that username
-to the `drush5 uli` command. For example:
+to the @drush5 uli@ command. For example:
-`drush5 uli "John Doe"`
+@drush5 uli "John Doe"@
[ssh]
diff --git a/03.managing/good-habits/chapter.md b/03.managing/good-habits/chapter.md
deleted file mode 100644
index a53d707..0000000
--- a/03.managing/good-habits/chapter.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-title: Advanced
-taxonomy:
- category: docs
----
-
-### Chapter 3
-
-# Advanced
-
-Get into the **nitty gritty** with these advanced topics
diff --git a/03.managing/good-habits/file-dir-perms/docs.md b/03.managing/good-habits/file-dir-perms/docs.md
deleted file mode 100644
index 9ead0c8..0000000
--- a/03.managing/good-habits/file-dir-perms/docs.md
+++ /dev/null
@@ -1,127 +0,0 @@
----
-title: TITLE
-slug: URI
-menu: MENU
-date: 08-08-2016
-published: true
-visible: true
-taxonomy:
- category: docs
-routes:
- aliases:
- - /URI
----
-Set Correct Permissions for Files You Copy Into Aegir
-
-When you copy files or directories into Aegir, Aegir will *usually*
-set the correct permissions. However, to avoid headaches, you should
-understand when and how to set correct permissions manually.
-
-Task: Set Correct Permissions For Files You Copy
-------------------------------------------------
-
-These steps will set all possible permissions for your site.
-
-1. [`ssh` in](ftp-ssh-access) to your Aegir account
-
-1. `cd` to the site-specific directory for your Aegir site. If your
- site is `foo.com`, this will be `sites/foo.com/` in the
- [platform](platform)
- directory.
-
-1. `chmod -R 775 libraries/* modules/* themes/*`
-
-1. `chmod -R 777 files/*`
-
-**** Use **777** here, not **775**
-
-**** Ignore any "Operation not permitted" warnings.
-
-1. `cd` into `sites/all`.
-
-1. `chmod -R 775 libraries/* modules/* themes/*`
-
-1. Now run the `Verify` task on every [platform](platform)
- and site affected by these new files and directories.
-
-More Information
-----------------
-
-### When Do You Need to Set Permissions Manually?
-
-Aegir **will** set correct permissions automatically when you upload
-files or directories using **SFTP** or **FTPS**.
-
-The exception are files in `sites/foo.com/files/`. If you **overwrite**
-a file that needs to be writable by the web server, you can cause
-problems, such as a broken layout.
-
-Aegir **will not** set correct permissions when:
-
-- files have been transferred via `rsync` or `scp` on the command line
-- files have been downloaded with `drush` on the command line
-- files have been extracted from `tar` or `zip` archives on the
- command line
-
-Every morning (in the local timezone for your server/datacenter), a
-[BOA](boa) maintenance script will automatically fix all these
-permissions.
-
-However, if you run Aegir tasks while the permissions are still
-incorrect,
-you can cause problems. You should fix permissions
-manually **before you run any Aegir tasks**.
-
-### What If You Don't Set These Permissions?
-
-- You can **lose write permissions** to your uploaded files if you
- run
- the `Clone` or `Migrate` task.
-
-- The **web server may lose write permissions**, which can break your
- site layout. Many site layouts require the web server to write
- temporary files to the `files/` directory.
-
-These issues will not resolve until the maintenance script runs in the
-morning.
-
-### Must You Set Permissions After Updates?
-
-**Yes**. When you download updated libraries, modules, or themes, these
-are new files. You must set correct permissions, just as you did with
-the original files.
-
-### Which Directories Cannot Be Changed?
-
-Never try to `chmod` the `files/`, `modules/`, `themes/` or
-`libraries/` directories themselves. Instead, `chmod` their
-subdirectories and files, by adding the `-R` switch and an asterisk
-(`*`).
-
-This command will **fail**:
-
-`chmod 777 files/`
-
-But this command is **correct**:
-
-`chmod 777 -R files/*`
-
-### "Operation Not Permitted"?
-
-If you `ssh` in and set correct permissions within the `files/`
-directory, you may see this error: `Operation not permitted.` This is
-expected, because your SSH user is neither an owner of this directory
-nor of any files owned or created by the web server.
-
-But this error can safely be ignored. The command will still set
-correct permissions for any files you have uploaded.
-
-References
-----------
-
-[Keeping Aegir Informed With Aegir Tasks](keeping-aegir-informed)
-
-[ftp-ssh-access]
-[platform]
-[sites-all-modules]
-[keeping-aegir-informed]
diff --git a/03.managing/good-habits/keeping-aegir-informed/docs.md b/03.managing/good-habits/keeping-aegir-informed/docs.md
deleted file mode 100644
index ad2fc74..0000000
--- a/03.managing/good-habits/keeping-aegir-informed/docs.md
+++ /dev/null
@@ -1,52 +0,0 @@
----
-title: TITLE
-slug: URI
-menu: MENU
-date: 08-08-2016
-published: true
-visible: true
-taxonomy:
- category: docs
-routes:
- aliases:
- - /URI
----
-When to Run "Verify" Before Other Aegir Tasks
-
-Before you run certain Aegir tasks, it's a good idea to run `Verify`.
-Although some tasks include `Verify` automatically, a manual `Verify`
-lets you troubleshoot problems before trying to run a complex task.
-
-Task: Verify Before Other Aegir Tasks
--------------------------------------
-
-- If you have copied any modules, themes, or libraries into this
- platform within the last 24 hours, you may need to
- [set correct permissions](file-dir-perms) and run `Verify` on both
- this platform
- and each of its sites. Make sure to `Verify` before running any
- other Aegir tasks.
-
-- Before running `Clone`, run `Verify` on the site and its platform.
-
-- After running `Clone`, run `Verify` on both the original and the
- cloned sites.
-
-- Before running `Migrate`, run `Verify` on the site and on both the
- current and the target platforms.
-
-- To [**rename a site**](rename-task), use `Migrate`, but
- **keep the site on the same platform**.
- (Never change a site's name and platform in the same
- step. This can lead to irreversible breakage.)
-
-References
-----------
-
-[Set Correct Permissions for Files You Copy Into Aegir](file-dir-perms)
-
-[Rename Your Aegir Site](rename-task)
-
-[ssh]
-[file-dir-perms]
-[rename-task]
diff --git a/03.managing/manage-aliases-redirects/docs.md b/03.managing/manage-aliases-redirects/docs.md
index b868ba0..044ad6a 100644
--- a/03.managing/manage-aliases-redirects/docs.md
+++ b/03.managing/manage-aliases-redirects/docs.md
@@ -11,59 +11,57 @@ routes:
aliases:
- /URI
---
+
How to Manage Aliases and Redirects
When you create a site in Aegir, there is a textarea where you can
enter aliases and a checkbox to set whether these aliases should
redirect to the main domain. Once the site is created, you can access
-these settings again by clicking the `Edit` tab.
+these settings again by clicking the @Edit@ tab.
-Task: Edit Aliases and Redirects
---------------------------------
+h2. Task: Edit Aliases and Redirects
-To edit the aliases and redirects for a site, **click the `Edit` tab**
+To edit the aliases and redirects for a site, *click the @Edit@ tab*
in the upper left.
On the Edit screen, you can add or remove aliases in the large
-`Domain aliases` textarea.
+@Domain aliases@ textarea.
-To make all these aliases into redirects, check `Redirect domain
-aliases to the main domain`.
+To make all these aliases into redirects, check @Redirect domain
+aliases to the main domain@.
-Task: Redirect to "www."
-------------------------
+h2. Task: Redirect to "www."
-If you want your main domain to begin with "`www.`", you may need to
+If you want your main domain to begin with "@www.@", you may need to
take an extra step.
If you are creating the site, no extra step is needed. Simply enter
-the `www.` domain as the main domain. For instance, you could enter
-`www.foo.com`. Aegir will add `foo.com` as an alias *automatically*.
+the @www.@ domain as the main domain. For instance, you could enter
+@www.foo.com@. Aegir will add @foo.com@ as an alias _automatically_.
-However, if you already created the site as `foo.com`, you cannot
-`Migrate` it to `www.foo.com` directly. Aegir has already created
-`www.foo.com` as an alias.
+However, if you already created the site as @foo.com@, you cannot
+@Migrate@ it to @www.foo.com@ directly. Aegir has already created
+@www.foo.com@ as an alias.
Instead:
-1. Use the `Migrate` task to move the site to some other domain,
- such as `anything.foo.com`.
+# Use the @Migrate@ task to move the site to some other domain,
+such as @anything.foo.com@.
-1. Then `Migrate` the site to `www.foo.com`.
+# Then @Migrate@ the site to @www.foo.com@.
-1. Finally, set the checkbox to enable redirects. Now a visit to
- `foo.com` will cause a 301 redirect to `www.foo.com`.
+# Finally, set the checkbox to enable redirects. Now a visit to
+ @foo.com@ will cause a 301 redirect to @www.foo.com@.
-More Information
-----------------
+h2. More Information
-### Can You Use .htaccess for Redirects?
+h3. Can You Use .htaccess for Redirects?
-**No.** Aegir and [Nginx](nginx) have no .htaccess file. You must use
+*No.* Aegir and "Nginx":nginx have no .htaccess file. You must use
the Aegir interface to manage your Nginx redirects.
If you need specialized aliases which cannot be created in this
interface (for instance, using regular expressions), contact
-[support](support).
+"support":support.
[nginx]
diff --git a/03.managing/modules/boost/docs.md b/03.managing/modules/boost/docs.md
deleted file mode 100644
index ef14ab9..0000000
--- a/03.managing/modules/boost/docs.md
+++ /dev/null
@@ -1,86 +0,0 @@
----
-title: TITLE
-slug: URI
-menu: MENU
-date: 08-08-2016
-published: true
-visible: true
-taxonomy:
- category: docs
-routes:
- aliases:
- - /URI
----
-Using the Boost Module for Caching
-
-The [Boost](https://drupal.org/project/boost) module caches full pages
-for **anonymous** visitors only. On our hosting, Boost can be used in
-conjuction with other caching systems such as [Speed
-Booster](cache-speed-booster)
-and [Redis.](cache-redis)
-
-Task: Enable Boost
-------------------
-
-Boost is supported in our Nginx server configuration, so you do not
-use an `.htaccess` file or need to do any other configuration.
-
-To use Boost, simply:
-
-1. **Enable** the module as usual, on the "Modules" admin page.
-
-1. If this is a custom platform in the `~/static` directory, and this
- is
- the first site on the platform for which you have enabled Boost,
- then you must also "Verify" this site in Aegir (see
- "Caution" below).
-
-**** With our built-in platforms, you do not need this extra step.
-
-Task: Disable Boost
--------------------
-
-You can disable Boost like any other module, on the "Modules" admin
-page.
-
-To disable Boost for a particular URL on the fly, add `?nocache=1`.
-This will also disable [Speed Boost](cache-speed-booster) for that URL.
-
-Caution
--------
-
-### Boost Needs a "cache/" Directory
-
-Boost requires a `cache/` directory in the platform.
-
-
-(Example: <code>~/static/my-platform-01/<strong>cache</strong>/</code>)
-
-This directory is automatically included on all
-our [built-in platforms](built-in-platforms).
-
-If you [add a custom platform](add-custom-platform), you can also
-trigger
-the creation of this directory with correct permissions with these
-steps:
-
-1. Enable the Boost module for one of the sites on this platform.
-
-1. Run the "Verify" task on this site.
-
-It is important that you use Aegir to create this directory in your
-custom platform. You shouldn't create it via FTPS, SFTP, or on the
-command
-line. If the directory has been copied during the site import
-procedure,
-you should delete and re-create it via Aegir, as explained above.
-
-References
-----------
-
-- [Using Speed Booster Caching](cache-speed-booster)
-
-- [How to Disable All Caching](cache-disable-all)
-
-- [How to Disable CSS and Javascript Caching](cache-disable-css-js)
-
diff --git a/03.managing/modules/chapter.md b/03.managing/modules/chapter.md
deleted file mode 100644
index a53d707..0000000
--- a/03.managing/modules/chapter.md
+++ /dev/null
@@ -1,11 +0,0 @@
----
-title: Advanced
-taxonomy:
- category: docs
----
-
-### Chapter 3
-
-# Advanced
-
-Get into the **nitty gritty** with these advanced topics
diff --git a/03.managing/modules/extra-builtin-modules/docs.md b/03.managing/modules/extra-builtin-modules/docs.md
deleted file mode 100644
index a1745d6..0000000
--- a/03.managing/modules/extra-builtin-modules/docs.md
+++ /dev/null
@@ -1,237 +0,0 @@
----
-title: TITLE
-slug: URI
-menu: MENU
-date: 08-08-2016
-published: true
-visible: true
-taxonomy:
- category: docs
-routes:
- aliases:
- - /URI
----
-Extra Built-In Modules on All Aegir Platforms
-
-Every Aegir 6.x and 7.x platform includes certain extra built-in
-modules. Some are enabled by default, others are only supported, and a
-few are disabled. On this page, you'll find a complete listing of
-these modules for the latest stable [BOA](boa) release. You'll also
-find more information about working with these modules on your Aegir
-sites and [platforms](platform).
-
-Supported, Enabled, Disabled: Complete List
--------------------------------------------
-
-This list of built-in modules is updated with each stable "BOA" release.
-
-### What do the Symbols Mean?
-
-- `[S]` **Supported**: This module may require custom rewrites on the
- web
- server level. Since you cannot do this with an `.htaccess` file on
- an Nginx server, we have added all required rewrites and
- configuration at the system level. Note: not all supported modules
- are actually bundled in the platforms; if the list does not include
- a `[B]` for a module, you need to download it. Often, the module
- listed as supported needs some pre-configuration on the
- `settings.php`
- file level, so [BOA](boa) comes with these settings pre-configured
- in the `global.inc` file. You can't access or edit this file, but it
- is
- included in every site's `settings.php` automatically.
-
-- `[B]` **Bundled**: The code for this module is included in the
- platform. You don't need to download it; you can simply enable
- it. (All bundled modules are supported, but not all supported
- modules
- are bundled.)
-
-- `[SE]` **Soft Enabled**: This module is enabled when you `Create` a
- "blank" site with Aegir, but if you disable it, the daily
- maintenance monitor will not turn it back on.
-
-- `[FE]` **Force Enabled**: If you disable this module, the daily
- monitor
- will enable it again.
-
-- `[FD]` **Force Disabled**: If you enable this module, the daily
- monitor will disable it again. (For instance, you can temporarily
- enable the `devel` or `dblog` module while you're developing a
- site,
- but if you forget to disable it, it'll get disabled automatically.)
-
-- `[NA]` **Special Modules**: This module is used without the need
- to enable it.
-
-- `[D6]` Included and/or Supported on **Drupal 6** platforms
-
-- `[D7]` Included and/or Supported on **Drupal 7** platforms
-
-### Contrib Modules [S]upported:
-
- ais ------------------------ [D7] ------ [S]
- audio ---------------------- [D6] ------ [S]
- backup_migrate ------------- [D6,D7] --- [S]
- ckeditor ------------------- [D6,D7] --- [S]
- fbconnect ------------------ [D6,D7] --- [S]
- fckeditor ------------------ [D6] ------ [S]
- imagecache ----------------- [D6,D7] --- [S]
- imagecache_external -------- [D6,D7] --- [S]
- responsive_images ---------- [D7] ------ [S]
- tinybrowser ---------------- [D6,D7] --- [S]
- tinymce -------------------- [D6] ------ [S]
- wysiwyg_spellcheck --------- [D6,D7] --- [S]
-
-### Contrib Modules [S]upported & [B]undled:
-
- advagg --------------------- [D6,D7] --- [S] [B]
- blockcache_alter ----------- [D6,D7] --- [S] [B]
- boost ---------------------- [D6,D7] --- [S] [B]
- cdn ------------------------ [D6,D7] --- [S] [B]
- config_perms --------------- [D6,D7] --- [S] [B]
- css_emimage ---------------- [D6,D7] --- [S] [B]
- dbtuner -------------------- [D6] ------ [S] [B]
- esi ------------------------ [D6,D7] --- [S] [B]
- expire --------------------- [D6,D7] --- [S] [B]
- filefield_nginx_progress --- [D6,D7] --- [S] [B]
- flood_control -------------- [D7] ------ [S] [B]
- force_password_change ------ [D6,D7] --- [S] [B]
- fpa ------------------------ [D6,D7] --- [S] [B]
- httprl --------------------- [D6,D7] --- [S] [B]
- login_security ------------- [D6,D7] --- [S] [B]
- nocurrent_pass ------------- [D7] ------ [S] [B]
- phpass --------------------- [D6] ------ [S] [B]
- private_upload ------------- [D6] ------ [S] [B]
- purge ---------------------- [D6,D7] --- [S] [B]
- readonlymode --------------- [D6,D7] --- [S] [B]
- reroute_email -------------- [D6,D7] --- [S] [B]
- securesite ----------------- [D6,D7] --- [S] [B]
- security_review ------------ [D6,D7] --- [S] [B]
- site_verify ---------------- [D6,D7] --- [S] [B]
- speedy --------------------- [D7] ------ [S] [B]
- taxonomy_edge -------------- [D6,D7] --- [S] [B]
- textile -------------------- [D6,D7] --- [S] [B]
- variable_clean ------------- [D6,D7] --- [S] [B]
- vars ----------------------- [D7] ------ [S] [B]
- views_content_cache -------- [D6,D7] --- [S] [B]
- views404 ------------------- [D6,D7] --- [S] [B]
-
-### Contrib Modules [S]upported & [B]undled & [F]orce[E]nabled:
-
- entitycache ---------------- [D7] ------ [S] [B] [FE]
- robotstxt ------------------ [D6,D7] --- [S] [B] [FE]
-
-### Special [NA] Contrib Modules [S]upported & [B]undled:
-
- cache_backport ------------- [D6] ------ [S] [B] [NA]
- redis ---------------------- [D6,D7] --- [S] [B] [NA]
-
-### Contrib Themes [S]upported & [B]undled & [S]oft[E]nabled:
-
- admin ---------------------- [D6,D7] --- [S] [B] [SE]
- rubik ---------------------- [D6,D7] --- [S] [B] [SE]
-
-### Contrib Modules [F]orce[D]isabled:
-
- css_gzip ------------------- [D6] -------------- [FD]
- devel ---------------------- [D6,D7] ----------- [FD]
- performance ---------------- [D6,D7] ----------- [FD]
- javascript_aggregator ------ [D6] -------------- [FD]
- l10n_update ---------------- [D6,D7] ----------- [FD]
- poormanscron --------------- [D6] -------------- [FD]
- supercron ------------------ [D6] -------------- [FD]
-
-### Core Modules [F]orce[D]isabled:
-
- cookie_cache_bypass -------- [D6] -------------- [FD]
- dblog ---------------------- [D6,D7] ----------- [FD]
- syslog --------------------- [D6,D7] ----------- [FD]
- update --------------------- [D6,D7] ----------- [FD]
-
-### Core Modules [F]orce[E]nabled:
-
- path_alias_cache ----------- [D6] -------------- [FE]
-
-### Drush Extensions [S]upported & [B]undled
-
-Drush Extensions:
-
- clean_missing_modules ------ [D6,D7] --- [S] [B]
- drush_ecl ------------------ [D7] ------ [S] [B]
- drush_make ----------------- [D6,D7] --- [S] [B]
- registry_rebuild ----------- [D6,D7] --- [S] [B]
-
-More Information
-----------------
-
-### Do These Modules Get Added to Your Custom Platforms?
-
-**Yes**, these modules will get automatically added to your custom
-platform in `~/static/`, but only if:
-
-1. You **add at least one site** to your custom platform,
-
-1. then **wait a day** for the maintenance monitor to run,
-
-1. then **run `Verify`** on the custom platform, to
- [keep Aegir informed](keeping-aegir-informed) about the new
- modules.
- If you skip this last step, Aegir will not know about the
- new modules.
-
-Read more about [adding a custom platform](add-custom-platform) to
-`~/static/`.
-
-It's probably a good idea to create blank site whenever you add a
-custom platform, so that you'll get these modules as soon as possible.
-
-### Where Are Modules Added to Custom Platforms?
-
-These "built-in" modules are added to your custom platforms using
-*symbolic links*, or *symlinks*.
-
-You won't see these symlinks in the `sites/` directory. Instead,
-they're in a subdirectory of the platform root.
-
-For 6.x platforms, the extra modules are symlinked in
-`modules/o_contrib/`.
-
-For 7.x platforms, the extra modules are symlinked in
-`modules/o_contrib_seven/`.
-
-Your SSH user can't `cd` to these directories. If you try, you'll get
-a warning.
-
-### How Can You Override Built-In Modules?
-
-Overriding built-in modules is easy. Drupal already has logic for
-overriding modules depending on the filesystem location. Before looking
-in the platform root, Drupal will look for each module in:
-
-- `sites/foo.com/modules/`, the site-specific directory, and then
-- `sites/all/modules/`, the platform-wide directory
-
-To override the built-in platform version of a particular module,
-place your copy in either location.
-
-We strongly recommend that you
-place **all contrib modules into `sites/all/modules/`**,
-and **never into `sites/foo.com/modules`**. Even
-if you'll only use the module on one site, the platform-wide
-`sites/all/modules` offers excellent Aegir support for future
-upgrades.
-
-By contrast, putting modules into the site-specific
-`sites/foo.com/modules/` can cause serious problems and even
-breakage. The site-specific directory is best saved for custom,
-one-off modules that you develop specifically for that site.
-
-Read more about [always placing contrib modules into
-`sites/all/modules`.](sites-all-modules)
-
-[boa]
-[platform]
-[add-custom-platform]
-[keeping-aegir-informed]
-[sites-all-modules]
diff --git a/03.managing/modules/modules-enabled-disabled/docs.md b/03.managing/modules/modules-enabled-disabled/docs.md
deleted file mode 100644
index 31ffe46..0000000
--- a/03.managing/modules/modules-enabled-disabled/docs.md
+++ /dev/null
@@ -1,102 +0,0 @@
----
-title: TITLE
-slug: URI
-menu: MENU
-date: 08-08-2016
-published: true
-visible: true
-taxonomy:
- category: docs
-routes:
- aliases:
- - /URI
----
-Modules Enabled or Disabled Automatically
-
-Every morning on your Aegir instance, a daily maintenance monitor
-enables some modules and disables others. You can consult the
-[complete list of built-in modules](extra-builtin-modules),
-but this doc covers the key modules that get turned on or off.
-
-Key Modules That Get Enabled
-----------------------------
-
-Every morning (in the timezone for your Aegir server), these modules
-get **enabled**:
-
-- [Path alias cache](http://pressflow.org) (D6 only)
-- [RobotsTxt](https://drupal.org/project/robotstxt) (D6 and D7).
-
-Key Modules That Get Disabled
------------------------------
-
-Every morning (in the timezone for your Aegir server), these modules
-get **disabled**:
-
-- [Background Process](https://drupal.org/project/background_process),
-- [Cookie Cache Bypass
- Advanced](https://drupal.org/project/cookie_cache_bypass_adv)
-- DBlog (core)
-- Syslog (core)
-- [Devel](https://drupal.org/project/devel),
-- [Javascript
- Aggregator](https://drupal.org/project/javascript_aggregator)
-- [Localization Update](https://drupal.org/project/l10n_update),
-- [Poormanscron](https://drupal.org/project/poormanscron),
-- [SuperCron](https://drupal.org/project/supercron),
-- [Ultimate Cron](https://drupal.org/project/ultimate_cron),
-- Update (core)
-
-- [Boost Crawler](https://drupal.org/project/boost) - this Boost's
- submodule feature
- is disabled on the fly, permanently, so it is not affected by the
- explained
- above automated maintenance workflow, but still should be
- listed here.
-
-These modules should never be used on a live site. They either aren't
-appropriate for a high performance system, or they aren't allowed for
-performance reasons.
-
-Again, for a full list of disabled modules, consult the
-[complete list of built-in modules](extra-builtin-modules)
-
-More Information
-----------------
-
-### Modules to Avoid?
-
-Even though it is not actually disabled,
-you should avoid the [Search 404](https://drupal.org/project/search404)
-module.
-
-### What About DBlog or Devel for Development?
-
-Although DBlog and Devel are disabled each morning, they can be useful
-for temporary debugging. You can enable and use these modules as
-usual. But they'll be disabled in the morning.
-
-#### DBlog Data Stays Intact
-
-Although DBlog gets disabled, the data collected in the `watchdog`
-table remains intact. To access this data easily, enable DBlog again.
-
-#### Beware dpm() and dpr()
-
-If you use Devel to debug a module, be very careful about adding
-`dpm()` or `dpr()` calls to your code. These functions depend on
-Devel, and they're extremely useful, but you must delete them when
-you're done debugging. If you forget to delete them before Devel gets
-disabled, your code will break, and probably take down your site.
-
-#### Prevent Module Disabling
-
-To avoid having these modules disabled, include `.devel.` or `.dev.` in
-the **main domain name**. Adding an alias is not enough. To keep these
-modules enabled, the `.devel.` or `.dev.` must be included in the main
-domain.
-
-References
-----------
-
-[Extra Built-In Modules on All Aegir Platforms](extra-builtin-modules)
diff --git a/03.managing/modules/override-module-aegir/docs.md b/03.managing/modules/override-module-aegir/docs.md
deleted file mode 100644
index fc4f314..0000000
--- a/03.managing/modules/override-module-aegir/docs.md
+++ /dev/null
@@ -1,122 +0,0 @@
----
-title: TITLE
-slug: URI
-menu: MENU
-date: 08-08-2016
-published: true
-visible: true
-taxonomy:
- category: docs
-routes:
- aliases:
- - /URI
----
-You can also *override*
-existing modules and themes with a new version.
-
-Overview: *Override* a Module or Theme
---------------------------------------
-
-You can *override* or module or theme that's already in the platform.
-For instance, you can upload a newer or development version. Drupal
-will use the version you have uploaded.
-
-You can override for the entire platform (`sites/all/modules`) or for
-one site (`sites/foo.com/modules`).
-
-Drupal decides which version of a module or theme to run based on its
-location in the filesystem. The order of precedence is:
-
-1. `sites/foo.com/modules/`
-2. `sites/all/modules`
-3. the platform `modules/` directory
-4. the platform `profiles/foo/modules` directory
-
-**Caution:** Overriding the wrong module or theme can *break all the
-sites on your platform*. In general, instead of upgrading, you should
-prepare a new platorm, and [migrate each site to the new
-platform](migrate-platform).
-Please read the "Caution" section below before deciding to override.
-
-Step-by-Step: *Override a Module or Theme for a Platform*
----------------------------------------------------------
-
-**Caution**: You should almost never override a module for an entire
-platform.
-But if you insist, here's how.
-
-1. Upload your module or theme to `sites/all/modules/` or
- `sites/all/themes/` on the platform.
-
-1. Within `sites/all/modules/` or `sites/all/themes/`, run
- `chmod -R 775` to set correct permissions.
-
-1. For each site on the platform, rebuild the registry with `drush rr`
- or the `Rebuild registry` Aegir task.
-
-1. For each site on the platform, run the `Backup` Aegir task.
-
-1. For each site on the platform, apply any necessary database updates.
- Use `drush dbup` or browse to `http:/foo.com/update.php`
-
-Step-by-Step: *Override* a Module or Theme for One Site
--------------------------------------------------------
-
-Overriding a module for one site is still dangerous, but at least you
-can quickly test it first on a copy.
-
-1. Make a test copy of your live site with the `Clone` task in Aegir.
- Example: `bar.dev.foo.com`
-
-1. Upload your module or theme to the site-specific directory **of the
- test site**. Example: `sites/bar.dev.foo.com/modules/`
-
-1. Within this directory, run `chmod -R 775` to set
- correct permissions.
-
-1. Rebuild the registry with `drush rr` or the `Rebuild registry` Aegir
- task for the site.
-
-1. In Aegir, run the `Backup` task for the test site.
-
-1. Apply any module updates. Use `drush dbup` or browse to
- `http://bar.dev.foo.com/update.php`.
-
-1. Inspect the test site. If nothing has broken, delete the test site,
- and repeat these steps for your live site.
-
-Caution
--------
-
-### Don't Override an "Older" Module Without Research
-
-Sometimes the built-in platforms seem to have "outdated" modules.
-Don't assume a lazy maintainer! The newer version might have an
-incompatibility or a bug that would bring down all the sites on the
-platform. Research carefully before deciding to override.
-
-### Never Hack Core!
-
-Although you can override modules, you can't override core. If you
-want to patch core, you'll need to
-[build your own custom platform.](custom-platform)
-(Please don't request that we patch core on a built-in platform.)
-
-But you've heard the saying, right? [*Never hack
-core!*](never-hack-core)
-We strongly encourage you to avoid patching core, even on your own
-custom platform.
-
-In fact, the core we offer on our built-in platforms has *already* had
-important patches and improvements applied. We optimize core for our
-hosting.
-
-If you choose to build your own platforms, we suggest you use the same
-core that we offer with our built-in platforms.
-We publish our customized cores at our [Omega8cc GitHub
-account](https://github.com/omega8cc/):
-
-- [Drupal 7](https://github.com/omega8cc/7x/) from Omega8cc
-- [Pressflow (Drupal 6)](https://github.com/omega8cc/pressflow6/) from
- Omega8cc
-
diff --git a/03.managing/running-scheduled-sites-cron-aegir/docs.md b/03.managing/running-scheduled-sites-cron-aegir/docs.md
index 58ae207..819d9d7 100644
--- a/03.managing/running-scheduled-sites-cron-aegir/docs.md
+++ b/03.managing/running-scheduled-sites-cron-aegir/docs.md
@@ -11,63 +11,56 @@ routes:
aliases:
- /URI
---
+
Drupal Cron on Aegir Sites
-What is "cron"? Why do your Drupal sites need it? From the [Drupal
-handbook](drupal-cron):
+What is "cron"? Why do your Drupal sites need it? From the "Drupal handbook":drupal-cron:
-> Many Drupal modules have tasks that have to take place from time
-> to time. Think of cron as the tolling of a bell, letting Drupal know
-> that it should perform the appropriate tasks.
+bq. Many Drupal modules have tasks that have to take place from time
+to time. Think of cron as the tolling of a bell, letting Drupal know
+that it should perform the appropriate tasks.
-Task: Schedule Cron for Your Aegir Sites
-----------------------------------------
+h2. Task: Schedule Cron for Your Aegir Sites
Each of your Aegir sites can run cron at a different interval. You
manage each site's scheduled cron interval by editing its site node in
the Aegir control panel.
-Step-By-Step: Schedule (or Disable) Cron
-----------------------------------------
+h2. Step-By-Step: Schedule (or Disable) Cron
-1. Within Aegir, click `Sites` to get a list of sites.
+# Within Aegir, click @Sites@ to get a list of sites.
-1. Click on your site. This brings you to the "site node" for
- that site.
+# Click on your site. This brings you to the "site node" for that site.
-1. Click `Edit`.
+# Click @Edit@.
-1. You'll see `Cron interval`, and a drop-down list of intervals to
- choose from. Choose your cron interval, and save the node.
+# You'll see @Cron interval@, and a drop-down list of intervals to
+ choose from. Choose your cron interval, and save the node.
-1. To **disable cron** for this site, select the `Disabled`
- interval instead.
+# To *disable cron* for this site, select the @Disabled@ interval instead.
Aegir will now run cron at this interval for your site.
-More Information
-----------------
+h2. More Information
-### How Often Does Aegir Run Cron by Default?
+h3. How Often Does Aegir Run Cron by Default?
By default, Aegir runs cron every 3 hours.
-### How Does Aegir Actually Run Cron?
+h3. How Does Aegir Actually Run Cron?
Aegir runs cron via the Drush command line backend.
-1. First it attempts `drush elysia-cron`. But this will only work if
- you
- have configured the [Elysia
- Cron](http://drupal.org/project/elysia_cron) module for your site.
+# First it attempts @drush elysia-cron@. But this will only work if you
+have configured the "Elysia Cron":http://drupal.org/project/elysia_cron module for your site.
-1. Then it attempts a standard cron with `drush cron` command.
+# Then it attempts a standard cron with @drush cron@ command.
-### Can You Use "Elysia Cron"?
+h3. Can You Use "Elysia Cron"?
Yes. See previous answer.
-### How Precise Are the Cron Intervals?
+h3. How Precise Are the Cron Intervals?
When you set the cron interval on Aegir, the minimum interval listed
is only 1 minute! In real life, the minimum precision you can expect
@@ -77,44 +70,40 @@ is within 3-5 minutes. So "1 minute" means "as soon as possible".
The exact cron time will depend on the number of sites you host and
the current load on the system.
-### Does Cron Ever Get Skipped?
+h3. Does Cron Ever Get Skipped?
At certain times of day, the system has a temporary high load, and the
scheduled cron may be skipped.
-High-load times include our [daily backup](backup-aegir) times:
+High-load times include our "daily backup":backup-aegir times:
-- Daily R1Soft/Idera filesystem backups
+* Daily R1Soft/Idera filesystem backups
-- Nightly database server backups
+* Nightly database server backups
These backups can prevent cron for up to a 1 hour window. The exact
timing depends on the server timezone.
-### How Can You Run Cron Manually?
+h3. How Can You Run Cron Manually?
-You **cannot** run cron using the normal Drupal method of accessing
-your
-site's `cron.php` (`http://foo.com/cron.php`) in your browser. For
-increased security and performance, **access to `cron.php` is
-disabled.**
+You *cannot* run cron using the normal Drupal method of accessing your
+site's @cron.php@ (@http://foo.com/cron.php@) in your browser. For
+increased security and performance, *access to @cron.php@ is disabled.*
But you can still run cron yourself whenever you need it. Here are
three ways to run cron manually:
-- Use the `Run cron` Aegir task (available as of BOA-2.0.4).
- Note that this method will run only the standard `drush cron`, and
- not
- `drush elysia-cron`. It may not work if you rely on the
- [Elysia Cron](http://drupal.org/project/elysia_cron) module.
+* Use the @Run cron@ Aegir task (available as of BOA-2.0.4).
+ Note that this method will run only the standard @drush cron@, and not
+ @drush elysia-cron@. It may not work if you rely on the
+ "Elysia Cron":http://drupal.org/project/elysia_cron module.
+
+* Click the "run cron manually" link at @admin/reports/status@ in the site.
-- Click the "run cron manually" link at `admin/reports/status` in
- the site.
+* On @SSH@ run @drush cron@ (or @drush elysia-cron@, if you have
+ configured the "Elysia Cron":http://drupal.org/project/elysia_cron module.)
-- On `SSH` run `drush cron` (or `drush elysia-cron`, if you have
- configured the [Elysia
- Cron](http://drupal.org/project/elysia_cron) module.)
-[drupal-cron]https://drupal.org/cron
+ [drupal-cron]https://drupal.org/cron
-[backup-aegir]link-to-backups-for-your-aegir-sites
+ [backup-aegir]link-to-backups-for-your-aegir-sites
diff --git a/03.managing/where-rename-task/docs.md b/03.managing/where-rename-task/docs.md
new file mode 100644
index 0000000..21839cd
--- /dev/null
+++ b/03.managing/where-rename-task/docs.md
@@ -0,0 +1,59 @@
+---
+title: TITLE
+slug: URI
+menu: MENU
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+routes:
+ aliases:
+ - /URI
+---
+
+Where Is the Rename Task?
+
+The Aegir admin panel offers a list of possible tasks, but there is no
+@Rename@ task.
+
+h2. Task: Rename Your Site's Main Domain
+
+To "rename" your site to a new main domain, *use the @Migrate@ task*.
+
+Do *not* change the platform. Instead, leave the platform unchanged,
+and simply enter the new domain for your site.
+
+h2. More Information
+
+h3. Never Change the Domain and the Platform in One Step
+
+The @Migrate@ tasks triggers many steps behind the scenes, so it is
+critical never to change both the domain name and the platform in one
+step. Doing so could make it impossible to run the @Backup@ task and
+undo any mistakes.
+
+If you're renaming the domain, keep the site on the same platform.
+
+If you're migrating to a new platform, keep the same domain name.
+
+h3. "www." Prefix Requires Special Handling
+
+If you want to add or remove the "www." prefix from your domain name, you will
+need an extra step.
+
+First, @Migrate@ the site to some other domain, like @anything.foo.com@.
+
+Then, @Migrate@ from @anything.foo.com@ to @www.foo.com@ or @foo.com@.
+
+The reason for the extra step is that Aegir automatically creates an
+_alias_ based on the main domain. The domain @foo.com@ gets an alias
+of @www.foo.com@, and the domain of @www.foo.com gets an alias of
+@foo.com@. You can't change a main domain to one of its aliases
+directly.
+
+h3. References
+
+"How to Manage Aliases and Redirects":manage-aliases-redirects
+
+[manage-aliases-redirects]
diff --git a/04.caching/cache-disable-all/docs.md b/04.caching/cache-disable-all/docs.md
index 6da86f1..cfe062e 100644
--- a/04.caching/cache-disable-all/docs.md
+++ b/04.caching/cache-disable-all/docs.md
@@ -11,52 +11,46 @@ routes:
aliases:
- /URI
---
+
How to Disable all Caching and Aggregation
Caching and aggregation are huge performance boosts, but when you're
developing your site (especially your theme), they can prevent you
from seeing your changes.
-Quickstart Guide to Disabling Caching
--------------------------------------
+h2. Quickstart Guide to Disabling Caching
If your layout is broken, and you're not sure whether caching is the
culprit, here are some steps to try, in order of difficulty. Most are
explained in more detail below.
-1. Add ?nocache=1 to the URL and reload.
-
-1. Add ?noredis=1 to the URL and reload.
+# Add ?nocache=1 to the URL and reload.
-1. Edit a node or block on the page. This can force the cache to
- reload.
+# Add ?noredis=1 to the URL and reload.
-1. If the page is a view, check whether you need to disable caching
- for
- the view.
+# Edit a node or block on the page. This can force the cache to
+ reload.
-1. Purge all Boost's caches and then "disable the
- module"#disable-boost.
- The order is very important here.
+# If the page is a view, check whether you need to disable caching for
+ the view.
-1. [Use a .dev. or .devel. alias](#caching-dev) for the site, visit
- the
- admin Performance page via this alias, and try disabling various
- caching settings.
+# Purge all Boost's caches and then "disable the module"#disable-boost.
+ The order is very important here.
-**** Drupal 6: `admin/settings/performance`
+# "Use a .dev. or .devel. alias":#caching-dev for the site, visit the
+ admin Performance page via this alias, and try disabling various
+ caching settings.
-**** Drupal 7: `admin/config/development/performance`
+** Drupal 6: @admin/settings/performance@
+** Drupal 7: @admin/config/development/performance@
-1. Use the [AdvAgg module](#use-advagg), or, if you're already using
- it,
- uninstall and delete it, if you have a copy in `sites/all/modules/`.
+# Use the "AdvAgg module":#use-advagg, or, if you're already using it,
+ uninstall and delete it, if you have a copy in @sites/all/modules/@.
If none of these solve your problem, keep reading to investigate
further.
-Overview: Disable Caching So You Can Change Settings
-----------------------------------------------------
+h2. Overview: Disable Caching So You Can Change Settings
On a standard Drupal site, you can disable caching and aggregation
settings on a site's "Performance" administrator page.
@@ -70,8 +64,7 @@ Note: some caching can only be disabled temporarily. When this caching
is enabled again, your settings on the Performance page will also be
overridden.
-Task: Disable Caching
----------------------
+h2. Task: Disable Caching
Here is a full list of all typical settings on the admin Performance
page. For each setting, we have the default value, and what you have
@@ -80,90 +73,84 @@ to do to change it.
These are the main actions you can take to disable different kinds of
caching settings:
-- [Use a `.dev.` or `.devel.` alias](#caching-dev)
-- [Disable Redis](#disable-redis)
-- [Disable Speed Booster](#disable-speed-booster)
-- [Disable Boost](#disable-boost)
-- [Use AdvAgg](#use-advagg)
+* "Use a @.dev.@ or @.devel.@ alias":#caching-dev
+* "Disable Redis":#disable-redis
+* "Disable Speed Booster":#disable-speed-booster
+* "Disable Boost":#disable-boost
+* "Use AdvAgg":#use-advagg
Note which action affects which settings in the charts below.
-### Drupal 6 Performance Page Settings
-
-Access this Drupal 6 Performance page at: `/admin/settings/performance`
-
- --------------------------- --------------------------- ------------------------------------------------------------------------------
- _. Setting _. Default Value _. How to Override
- Caching Mode Forced as Normal "Use `.dev.` or `.devel.`":#caching-dev
- Minimum Cache Lifetime Forced as none "Disable Redis":#disable-redis
- Page Cache Maximum Age Forced as none "Disable Redis":#disable-redis
- Page Compression Always Forced as Disabled Cannot be disabled (Nginx)
- Block Cache Never Forced No action needed.
- Optimize CSS Files Forced Enabled (see note) [Disable Speed Booster](#disable-speed-booster) and "Boost":#disable-boost.
- Optimize Javascript Files Forced Enabled (see note) [Disable Speed Booster](#disable-speed-booster) and "Boost":#disable-boost.
- --------------------------- --------------------------- ------------------------------------------------------------------------------
-
-Note: if [AdvAgg 6.x](#use-advagg) is present (even if it's not enabled
-for this site), then both **Optimize CSS Files** and *Optimize
-Javascript Files* are Forced *Disabled*. You must [configure
-AdvAgg](module-advagg)
+h3. Drupal 6 Performance Page Settings
+
+Access this Drupal 6 Performance page at: @/admin/settings/performance@
+
+| _. Setting | _. Default Value | _. How to Override |
+| Caching Mode | Forced as Normal | "Use @.dev.@ or @.devel.@":#caching-dev |
+| Minimum Cache Lifetime | Forced as none | "Disable Redis":#disable-redis |
+| Page Cache Maximum Age | Forced as none | "Disable Redis":#disable-redis |
+| Page Compression | Always Forced as Disabled | Cannot be disabled (Nginx) |
+| Block Cache | Never Forced | No action needed. |
+| Optimize CSS Files | Forced Enabled (see note) | "Disable Speed Booster":#disable-speed-booster and "Boost":#disable-boost. |
+| Optimize Javascript Files | Forced Enabled (see note) | "Disable Speed Booster":#disable-speed-booster and "Boost":#disable-boost. |
+
+Note: if "AdvAgg 6.x":#use-advagg is present (even if it's not enabled
+for this site), then both *Optimize CSS Files* and *Optimize
+Javascript Files* are Forced _Disabled_. You must "configure AdvAgg":module-advagg
instead.
-### Drupal 7 Performance Page Settings
+h3. Drupal 7 Performance Page Settings
-Access the Drupal 7 Performance page at:
-`admin/config/development/performance`).
+Access the Drupal 7 Performance page at: @admin/config/development/performance@).
- ---------------------------------- --------------------------- ------------------------------------------
- _. Setting _. Default Value _. How to Override
- Cache Pages For Anonymous Users Forced Enabled "Use `.dev.` or `.devel.`":#caching-dev
- Minimum Cache Lifetime Forced as none "Disable Redis":#disable-redis
- Expiration Of Cached Pages Forced as none "Disable Redis":#disable-redis
- Compress Cached Pages Always Forced as Disabled Cannot be disabled (Nginx)
- Aggregate And Compress CSS Files Forced Enabled "Use `.dev.` or `.devel.`":#caching-dev
- Aggregate Javascript Files Forced Enabled "Use `.dev.` or `.devel.`":#caching-dev
- ---------------------------------- --------------------------- ------------------------------------------
+| _. Setting | _. Default Value | _. How to Override |
+| Cache Pages For Anonymous Users | Forced Enabled | "Use @.dev.@ or @.devel.@":#caching-dev |
+| Minimum Cache Lifetime | Forced as none | "Disable Redis":#disable-redis |
+| Expiration Of Cached Pages | Forced as none | "Disable Redis":#disable-redis |
+| Compress Cached Pages | Always Forced as Disabled | Cannot be disabled (Nginx) |
+| Aggregate And Compress CSS Files | Forced Enabled | "Use @.dev.@ or @.devel.@":#caching-dev |
+| Aggregate Javascript Files | Forced Enabled | "Use @.dev.@ or @.devel.@":#caching-dev |
h3. Task: Use a ".dev." or ".devel." Alias
-#### Overview: The ".dev." or ".devel." Alias
+h4. Overview: The ".dev." or ".devel." Alias
-Whenever you access a site with an alias that includes `.dev.` or
-`.devel.`, certain caching and aggregation settings, which are normally
+Whenever you access a site with an alias that includes @.dev.@ or
+@.devel.@, certain caching and aggregation settings, which are normally
forced as enabled, can be disabled on the Performance page. See the
tables above for which settings are affected by this alias.
-#### Step-by-Step: Add a ".dev." or ".devel." Alias
+h4. Step-by-Step: Add a ".dev." or ".devel." Alias
-1. In Aegir, click "Sites".
+# In Aegir, click "Sites".
-1. Click your site name. This brings to your site node.
+# Click your site name. This brings to your site node.
-1. Click "edit".
+# Click "edit".
-1. Add an alias that includes `.dev.` or `.devel.`
+# Add an alias that includes @.dev.@ or @.devel.@
-**** Note: the alias **must include both periods**.
+** Note: the alias *must include both periods*.
-***** `bar.dev.foo.com` and `bar.devel.foo.com` will work.
+*** @bar.dev.foo.com@ and @bar.devel.foo.com@ will work.
-***** `devel.foo.com` and `dev_foo.com` will **not** work.
+*** @devel.foo.com@ and @dev_foo.com@ will *not* work.
-***** The exception is a domain which *begins* with `dev.`; so
-`dev.foo.com` will still work.
+*** The exception is a domain which _begins_ with @dev.@; so
+@dev.foo.com@ will still work.
-1. Save the node and wait until the Verify task completes.
- You can now access your site via this alias! Visit the Performance
- page via this alias to change the desired settings.
+# Save the node and wait until the Verify task completes.
+ You can now access your site via this alias! Visit the Performance
+ page via this alias to change the desired settings.
-The public domain name for this site will *not* be affected. If you
+The public domain name for this site will _not_ be affected. If you
want to change the behavior for the public site, you will need to try
one of the other actions, such as disabling Speed Booster.
-Using `.dev.` or `.devel.` will *allow* to disable caching, but it does
+Using @.dev.@ or @.devel.@ will _allow_ to disable caching, but it does
not actually disable anything automatically. The one thing it does do
-is set the [TTL](ttl) (cache time) for Speed Booster down to 1 second.
+is set the "TTL":ttl (cache time) for Speed Booster down to 1 second.
(Since it uses a cookie, bots are not affected.)
@@ -183,34 +170,34 @@ Boost is an ordinary module, and can be disabled on the Modules admin
page as usual.
You can also disable Boost for any URL on the fly by adding
-`?nocache=1`. This will also disable Speed Booster for that URL.
+@?nocache=1@. This will also disable Speed Booster for that URL.
h3. Task: Use AdvAgg to Disable CSS and Javascript Aggregation
(copy section from module-advagg once module-advagg is approved)
-More Information
-----------------
+h2. More Information
-### Which Caching is Enabled Automatically?
+h3. Which Caching is Enabled Automatically?
Our hosting comes with certain caching/aggregation enabled and active
-**automatically**. You can disable these, but only **temporarily**.
+*automatically*. You can disable these, but only *temporarily*.
-- [Redis caching](cache-redis)
-- [Speed Booster caching](cache-speed-booster)
-- Nginx (web server) caching, which cannot be disabled
+* "Redis caching":cache-redis
+* "Speed Booster caching":cache-speed-booster
+* Nginx (web server) caching, which cannot be disabled
-### Which Caching is Supported But Not Enabled Automatically?
+h3. Which Caching is Supported But Not Enabled Automatically?
-Our hosting also includes caching/aggregation which is *supported*,
+Our hosting also includes caching/aggregation which is _supported_,
but not enabled by default. If you have enabled this caching, you may
need to disable it.
-- [Boost module](module-module), which is included but not enabled.
-- [AdvAgg module](module-advagg), which is supported but must
- be downloaded.
+* "Boost module":module-module, which is included but not enabled.
+* "AdvAgg module":module-advagg, which is supported but must be downloaded.
+
+
[redis]https://drupal.org/project/redis
[module-advagg]
diff --git a/04.caching/cache-disable-css-js/docs.md b/04.caching/cache-disable-css-js/docs.md
index 22e39b6..74d9677 100644
--- a/04.caching/cache-disable-css-js/docs.md
+++ b/04.caching/cache-disable-css-js/docs.md
@@ -11,23 +11,22 @@ routes:
aliases:
- /URI
---
+
How to Disable CSS and Javascript Aggregation
-Problem: Your Layout Keeps Breaking
------------------------------------
+h2. Problem: Your Layout Keeps Breaking
Does the layout on your Drupal site break whenever you clear the
cache? Or, do you edit your CSS or Javascript files, clear the cache,
and not see any changes?
-Solution: Disable CSS/Javascript Aggregation
---------------------------------------------
+h2. Solution: Disable CSS/Javascript Aggregation
-The problem may be CSS and Javascript *aggregation*. To increase
-performance, CSS and Javascript files are by default *aggregated* into
+The problem may be CSS and Javascript _aggregation_. To increase
+performance, CSS and Javascript files are by default _aggregated_ into
single files with unique names. The pages of your Drupal site only
load these aggregated files, rather than the source files (like
-`styles.css`).
+@styles.css@).
If you disable aggregation, then the pages should load your source
files without any problem.
@@ -38,93 +37,82 @@ disabling aggregation is not allowed* in our hosted environment.
However, for debugging and theme development, you can follow these
steps to disable aggregation on the fly or temporarily.
-### How to Disable Aggregation On The Fly With a ".dev." Alias
+h3. How to Disable Aggregation On The Fly With a ".dev." Alias
If you just need to disable aggregation for your own personal
development, simply:
-1. Create an alias for the site that includes `.dev.` or `.devel.`
-
-**** Example: `bar.dev.foo.com`
+# Create an alias for the site that includes @.dev.@ or @.devel.@
-**** Make sure you include both periods in `.dev.` or `.devel.`
-(The exception is a domain which *begins* with `dev.`; so,
-`dev.foo.com` will still work.)
+** Example: @bar.dev.foo.com@
-1. Through this alias, go to the "Performance" admin page and disable
- CSS and Javascript aggregation.
+** Make sure you include both periods in @.dev.@ or @.devel.@
+ (The exception is a domain which _begins_ with @dev.@; so,
+ @dev.foo.com@ will still work.)
-**** Drupal 6: `admin/settings/performance`
+# Through this alias, go to the "Performance" admin page and disable
+ CSS and Javascript aggregation.
-**** Drupal 7: `admin/config/development/performance`
+** Drupal 6: @admin/settings/performance@
+** Drupal 7: @admin/config/development/performance@
Now aggregation will be disabled when you browse the site through this
-`.dev.` or `.devel.` alias.
+@.dev.@ or @.devel.@ alias.
-You can use this private `.dev.` alias for as long as you like.
+You can use this private @.dev.@ alias for as long as you like.
Aggregation will still be enabled when the public accesses this site
through its main domain name.
You should be able to develop your theme with the alias, and then
eventually see your changes get aggregated in the public version.
How long it takes depends on your caching settings,
-especially [Speed Booster](cache-speed-booster).
+especially "Speed Booster":cache-speed-booster.
-### How to Disable Aggregation On Your Actual Site Temporarily
+h3. How to Disable Aggregation On Your Actual Site Temporarily
-If your live site is mysteriously broken, you may need to
-**temporarily**
+If your live site is mysteriously broken, you may need to *temporarily*
disable aggregation until the problematic theme or module is fixed
-by adding these settings to `local.settings.php`:
-
-1. Create an empty control file at:
- `sites/foo.com/modules/local-allow.info`
+by adding these settings to @local.settings.php@:
-1. In Aegir, run the "Reset password" task on your site. Wait until
- the
- task finishes. Now `local.settings.php` is writable.
+# Create an empty control file at:
+ @sites/foo.com/modules/local-allow.info@
-1. Add these lines to `local.settings.php`:
- `unset($conf['preprocess_css']);`
- `unset($conf['preprocess_js']);`
+# In Aegir, run the "Reset password" task on your site. Wait until the
+ task finishes. Now @local.settings.php@ is writable.
-1. Go to the Performance page. Now you can disable CSS and
- Javascript aggregation.
+# Add these lines to @local.settings.php@:
+ @unset($conf['preprocess_css']);@
+ @unset($conf['preprocess_js']);@
-1. Disabling aggregation **permanently** is **not allowed** in our
- hosted
- environment. Go now and solve your issue. Then continue with these
- steps to return the system to normal.
+# Go to the Performance page. Now you can disable CSS and Javascript aggregation.
-1. Remove or comment the two lines you added to `local.settings.php`.
- Save. Aggregation is now enabled again.
+# Disabling aggregation *permanently* is *not allowed* in our hosted
+ environment. Go now and solve your issue. Then continue with these
+ steps to return the system to normal.
-1. Make sure your website loads properly. A typo in
- `local.settings.php` can break your entire site.
+# Remove or comment the two lines you added to @local.settings.php@.
+ Save. Aggregation is now enabled again.
-1. In Aegir, run "Verify" on your site. This restores
- `local.settings.php` to its safe, unwritable state.
+# Make sure your website loads properly. A typo in
+ @local.settings.php@ can break your entire site.
-Caution
--------
+# In Aegir, run "Verify" on your site. This restores
+ @local.settings.php@ to its safe, unwritable state.
-Disabling aggregation like this when you have [AdvAgg
-7.x](module-advagg)
-enabled may cause some warnings, since [AdvAgg 7.x](module-advagg)
-expects the Drupal aggregation to be *enabled* in order for this module
-to function properly.
-For [AdvAgg 6.x](module-advagg), it is not a problem, since this version
-expects
-the Drupal aggregation to be *disabled*.
+h2. Caution
-References
-----------
+Disabling aggregation like this when you have "AdvAgg 7.x":module-advagg
+enabled may cause some warnings, since "AdvAgg 7.x":module-advagg
+expects the Drupal aggregation to be _enabled_ in order for this module to function properly.
+For "AdvAgg 6.x":module-advagg, it is not a problem, since this version expects
+the Drupal aggregation to be _disabled_.
-- [How to Edit settings.php on Aegir](edit-settings-php)
+h2. References
-- [How to Disable All Caching](cache-disable-all)
+* "How to Edit settings.php on Aegir":edit-settings-php
-- [Using the AdvAgg Module.](module-advagg)
+* "How to Disable All Caching":cache-disable-all
-- [Using Speed Booster Caching](cache-speed-booster).
+* "Using the AdvAgg Module.":module-advagg
+* "Using Speed Booster Caching":cache-speed-booster.
diff --git a/04.caching/cache-redis/docs.md b/04.caching/cache-redis/docs.md
index 1c84e73..193c5c5 100644
--- a/04.caching/cache-redis/docs.md
+++ b/04.caching/cache-redis/docs.md
@@ -11,71 +11,64 @@ routes:
aliases:
- /URI
---
+
Using Redis Caching
-What Is Redis Caching?
-----------------------
+h2. What Is Redis Caching?
-The [Redis module](redis) implements caching in Drupal using the [Redis
-backend.](http://redis.io/) This caching works both for logged in users
+The "Redis module":redis implements caching in Drupal using the "Redis
+backend.":http://redis.io/ This caching works both for logged in users
and for anonymous requests which have not yet been cached with
-[Boost](module-boost) or [Speed Booster](cache-speed-booster).
+"Boost":module-boost or "Speed Booster":cache-speed-booster.
-This module is included and active by default on all platforms based on
-6.x and 7.x core.
+This module is included and active by default on all platforms based on 6.x and 7.x core.
-Task: How to Disable Redis Caching
-----------------------------------
+h2. Task: How to Disable Redis Caching
-You are not allowed to disable Redis caching permanently, but you can
-disable
+You are not allowed to disable Redis caching permanently, but you can disable
Redis temporarily for debugging.
-#### How to Disable Redis on Any URL
+h4. How to Disable Redis on Any URL
You can disable the Redis cache for any URL on the fly by adding
-`?noredis=1` at the end.
+@?noredis=1@ at the end.
-For example, to disable Redis caching for `http://foo.com/node/1`,
-browse
-to: `http://foo.com/node/1?redis=1`
+For example, to disable Redis caching for @http://foo.com/node/1@, browse
+ to: @http://foo.com/node/1?redis=1@
-#### How to Disable Redis Completely (and Temporarily)
+h4. How to Disable Redis Completely (and Temporarily)
To (temporarily) disable Redis for debugging, you can create an empty
control file at a special location.
-- To disable Redis for a particular **site**:
- `/sites/foo.com/modules/redis_cache_disable.info`
+* To disable Redis for a particular *site*: @/sites/foo.com/modules/redis_cache_disable.info@
-- To disable Redis for the entire **platform**:
- `/sites/all/modules/redis_cache_disable.info`
+* To disable Redis for the entire *platform*: @/sites/all/modules/redis_cache_disable.info@
-If the `Migrate` or `Clone` task in Aegir fails with unexpected errors
-for an otherwise working site, we recommend that you temporarily disable
-Redis,
+If the @Migrate@ or @Clone@ task in Aegir fails with unexpected errors
+for an otherwise working site, we recommend that you temporarily disable Redis,
run the task again, and re-enable Redis afterwards.
If Redis still causes problems, you should leave it disabled and wait
until the next morning, when the Redis cache server is fully restarted.
Then enable Redis again.
-Problems may happen when you use the `Migrate` task to `Rename` the
-site to a different name, and then `Rename` a separate clone of the
+Problems may happen when you use the @Migrate@ task to @Rename@ the
+site to a different name, and then @Rename@ a separate clone of the
site, such as a dev or staging copy, to the original main domain
name. In the Redis cache, the site name is used as a cache key, so
this situation may confuse both Aegir and the site itself because of
outdated entries in the Redis cache.
Disabling Redis permanently is not allowed in our hosted environment,
-unless our [support staff](support) gives you an exception.
+unless our "support staff":support gives you an exception.
+
+h2. References
-References
-----------
+* "How to Disable All Caching":cache-disable-all
-- [How to Disable All Caching](cache-disable-all)
+* "How to Disable CSS and Javascript Caching":cache-disable-css-js
-- [How to Disable CSS and Javascript Caching](cache-disable-css-js)
[redis]https://drupal.org/project/redis
[module-advagg]
diff --git a/04.caching/cache-speed-booster/docs.md b/04.caching/cache-speed-booster/docs.md
index f7df5ca..545cfea 100644
--- a/04.caching/cache-speed-booster/docs.md
+++ b/04.caching/cache-speed-booster/docs.md
@@ -11,10 +11,10 @@ routes:
aliases:
- /URI
---
+
Using Speed Booster Caching
-What Is Speed Booster Caching?
-------------------------------
+h2. What Is Speed Booster Caching?
"Speed Booster" is not a Drupal module, but our special, system-level
configuration. Speed Booster works with any version of Drupal. It is
@@ -23,116 +23,109 @@ enabled by default.
Speed Booster caches full pages, both for anonymous visitors and for
logged in users. Each logged-in user gets a separate cache.
-Tasks: Working With Speed Booster
----------------------------------
+h2. Tasks: Working With Speed Booster
-### How to Disable Speed Booster
+h3. How to Disable Speed Booster
-#### How to Disable Speed Booster on Any URL
+h4. How to Disable Speed Booster on Any URL
You can disable the Speed Booster cache on any URL, on demand, by
-adding `?nocache=1` at the end.
+adding @?nocache=1@ at the end.
For example, to disable Speed Booster caching for
-`http://foo.com/node/1`, browse to: `http://foo.com/node/1?nocache=1`
+ @http://foo.com/node/1@, browse to: @http://foo.com/node/1?nocache=1@
-This will also disable [Boost](module-boost), if it is enabled, for
+This will also disable "Boost":module-boost, if it is enabled, for
that URL.
-#### When is Speed Booster Automatically Disabled?
+h4. When is Speed Booster Automatically Disabled?
-Speed Booster is also **automatically disabled** for certain pages:
-`user/*`, `admin/*`, all HTTPS requests.
+Speed Booster is also *automatically disabled* for certain pages:
+@user/*@, @admin/*@, all HTTPS requests.
Speed Booster is also disabled for 15 seconds after any POST request.
This includes any form submission, even for anonymous visitors.
-#### How to Reduce Speed Booster to 1 Second With ".dev."
+h4. How to Reduce Speed Booster to 1 Second With ".dev."
-By default, Speed Booster is set to be valid ([TTL](ttl)) for:
+By default, Speed Booster is set to be valid ("TTL":ttl) for:
-- 10 seconds for normal visitors (both anonymous and logged in)
-- 24 hours for known bots
+* 10 seconds for normal visitors (both anonymous and logged in)
+* 24 hours for known bots
These values are hardcoded.
-However, if the domain for the site includes `.dev.` or `.devel.`,
-the TTL is lowered to **1 second** (but not for known bots).
+However, if the domain for the site includes @.dev.@ or @.devel.@,
+the TTL is lowered to *1 second* (but not for known bots).
-You can create a `.dev.` alias for your site by editing the site node
+You can create a @.dev.@ alias for your site by editing the site node
in Aegir.
-Note: both periods in `.dev.` or `.devel.` are required. You can use
-`bar.dev.foo.com`, but not `devel.foo.com` or `dev-foo.com`. The
-exception is a domain which *begins* with `dev.`;
-so, `dev.foo.com` will still work.
+Note: both periods in @.dev.@ or @.devel.@ are required. You can use
+@bar.dev.foo.com@, but not @devel.foo.com@ or @dev-foo.com@. The
+exception is a domain which _begins_ with @dev.@;
+so, @dev.foo.com@ will still work.
Speed Booster will continue to work normally when the site is accessed
through the live domain name.
-#### How to Disable Speed Booster Completely (and Temporarily)
+h4. How to Disable Speed Booster Completely (and Temporarily)
-If you need to force a 1-second TTL for the public domain name, which
-will
+If you need to force a 1-second TTL for the public domain name, which will
effectively disable Speed Booster (the 1-second TTL serves as a minimum
-required for active DoS-protection), you will need to edit
-`local.settings.php`.
+required for active DoS-protection), you will need to edit @local.settings.php@.
This file is not writable by default, but these steps will temporarily
unlock it for editing.
-1. Create an empty control file at:
- `sites/foo.com/modules/local-allow.info`
+# Create an empty control file at:
+ @sites/foo.com/modules/local-allow.info@
-1. In Aegir, run the "Reset password" task on your site. Wait until
- the
- task finishes. Now `local.settings.php` is writable.
+# In Aegir, run the "Reset password" task on your site. Wait until the
+ task finishes. Now @local.settings.php@ is writable.
-1. Set a site-wide 1-second TTL, by adding this line to
- `local.settings.php`: `header('X-Accel-Expires: 1');`
+# Set a site-wide 1-second TTL, by adding this line to
+ @local.settings.php@: @header('X-Accel-Expires: 1');@
-1. You can also use this conditionally, per URL. For example,
- to lower the TTL only for the site's homepage, use:
- `if (preg_match("/^/$/", $_SERVER['REQUEST_URI'])) {`
- @ header('X-Accel-Expires: 1');@
- `}`
+# You can also use this conditionally, per URL. For example,
+ to lower the TTL only for the site's homepage, use:
+ @if (preg_match("/^\/$/", $_SERVER['REQUEST_URI'])) {@
+ @ header('X-Accel-Expires: 1');@
+ @}@
-1. Disabling the Speed Booster cache TTL **permanently** is **not
- allowed**
- in our hosted environment. Go now and solve your issue.
- Then continue with these steps to return the system to normal.
+# Disabling the Speed Booster cache TTL *permanently* is *not allowed*
+ in our hosted environment. Go now and solve your issue.
+ Then continue with these steps to return the system to normal.
-1. Remove or comment the `X-Accel-Expires` line(s) in
- `local.settings.php`. Save. Speed Booster is now enabled again.
+# Remove or comment the @X-Accel-Expires@ line(s) in
+ @local.settings.php@. Save. Speed Booster is now enabled again.
-1. Make sure your website loads properly. A typo in
- `local.settings.php` can break your entire site.
+# Make sure your website loads properly. A typo in
+ @local.settings.php@ can break your entire site.
-1. In Aegir, run "Verify" on your site. This restores
- `local.settings.php` to its safe, unwritable state.
+# In Aegir, run "Verify" on your site. This restores
+ @local.settings.php@ to its safe, unwritable state.
-### How to Enable ESI Microcaching
+h3. How to Enable ESI Microcaching
-[ESI microcaching](http://groups.drupal.org/node/197478) allows you to
+"ESI microcaching":http://groups.drupal.org/node/197478 allows you to
use a separate microcache for ESI/SSI includes, with its own TTL,
-which is set by default to 15 seconds. While Speed Booster caches the
-rest
-of the page separately, these small, included bits can be used to
-deliver
+which is set by default to 15 seconds. While Speed Booster caches the rest
+of the page separately, these small, included bits can be used to deliver
parts of the page dynamically even if the main Speed Booster cache TTL
is set to 1 hour or longer.
-An example is a personalized message like "Logged in as *johndoe*".
+An example is a personalized message like "Logged in as _johndoe_".
Instead of rebuilding the entire page for this user, only _this
message_ is rebuilt. ESI microcaching offers a huge performance boost.
-The [ESI module](http://drupal.org/project/esi) is included in all
+The "ESI module":http://drupal.org/project/esi is included in all
built-in 6.x platforms. However, you will need to enable and configure
-this module. Please consult the [module
-documentation](http://drupal.org/project/esi) for details.
+this module. Please consult the "module
+documentation":http://drupal.org/project/esi for details.
-### How to Force Different Cache TTL Values
+h3. How to Force Different Cache TTL Values
-You can set the Speed Booster cache to last *longer* for anonymous
+You can set the Speed Booster cache to last _longer_ for anonymous
visitors. You can set this TTL for the entire platform, or set it
separately for each site.
@@ -140,53 +133,50 @@ You set this TTL using specially named "control files". These files
are empty. You just need to create the correct filename in the correct
location.
-#### To force a 15-minute cache TTL:
+h4. To force a 15-minute cache TTL:
-- platform-wide: `sites/all/modules/nginx_cache_quarter.info`
-- per site: `sites/foo.com/modules/nginx_cache_quarter.info`
+* platform-wide: @sites/all/modules/nginx_cache_quarter.info@
+* per site: @sites/foo.com/modules/nginx_cache_quarter.info@
-#### To force a 1-hour cache TTL:
+h4. To force a 1-hour cache TTL:
-- platform-wide: `sites/all/modules/nginx_cache_hour.info`
-- per site: `sites/foo.com/modules/nginx_cache_hour.info`
+* platform-wide: @sites/all/modules/nginx_cache_hour.info@
+* per site: @sites/foo.com/modules/nginx_cache_hour.info@
-#### To force a 24-hour cache TTL, use:
+h4. To force a 24-hour cache TTL, use:
-- platform wide: `sites/all/modules/nginx_cache_day.info`
-- per site: `sites/foo.com/modules/nginx_cache_day.info`
+* platform wide: @sites/all/modules/nginx_cache_day.info@
+* per site: @sites/foo.com/modules/nginx_cache_day.info@
These settings will not override the cache for logged in users. They
are only for anonymous visitors.
To avoid a broken CSS layout with these longer caches,
-[use the AdvAgg module](module-advagg).
+"use the AdvAgg module":module-advagg.
-More Information
-----------------
+h2. More Information
-### Does Speed Booster Cache Mobile Devices Separately?
+h3. Does Speed Booster Cache Mobile Devices Separately?
Yes. Speed Booster supports separate caches per mobile device. It
is safe to use separate themes or content for mobile devices.
-We use simple logic to determine the kind of device, and there are
-separate
-cache bins for `mobile-tablet`, `mobile-smart` and `mobile-other`.
-[Review the code here.](http://bit.ly/wYz6PG)
+We use simple logic to determine the kind of device, and there are separate
+cache bins for @mobile-tablet@, @mobile-smart@ and @mobile-other@.
+"Review the code here.":http://bit.ly/wYz6PG
You can access this special variable value set by Nginx also in
-your Drupal code (module or theme) via `$_SERVER['USER_DEVICE']`
+your Drupal code (module or theme) via @$_SERVER['USER_DEVICE']@
-References
-----------
+h2. References
-- [ESI module](http://drupal.org/project/esi)
+* "ESI module":http://drupal.org/project/esi
-- [How to Edit settings.php on Aegir](edit-settings-php)
+* "How to Edit settings.php on Aegir":edit-settings-php
-- [How to Disable All Caching](cache-disable-all)
+* "How to Disable All Caching":cache-disable-all
-- [How to Disable CSS and Javascript Caching](cache-disable-css-js)
+* "How to Disable CSS and Javascript Caching":cache-disable-css-js
[advagg]http://drupal.org/project/advagg
[ttl]https://en.wikipedia.org/wiki/Time_to_live
diff --git a/05.advanced/backups-for-your-aegir-sites/docs.md b/05.advanced/backups-for-your-aegir-sites/docs.md
index 4cd5520..12d471e 100644
--- a/05.advanced/backups-for-your-aegir-sites/docs.md
+++ b/05.advanced/backups-for-your-aegir-sites/docs.md
@@ -11,6 +11,7 @@ routes:
aliases:
- /URI
---
+
Backups for Your Aegir Sites at Omega8.cc
Backups are essential for preserving your sites (and your sanity). At
@@ -18,152 +19,141 @@ Omega8.cc, we offer extra protection through free, automated backups.
Aegir itself also performs many backups automatically. You can access
these backups easily.
-Task: How to Access Your Backups
---------------------------------
+h2. Task: How to Access Your Backups
-With so many automated backups, you usually don't have to *make*
-backups. Instead, here is how to *use* the backups you already have.
+With so many automated backups, you usually don't have to _make_
+backups. Instead, here is how to _use_ the backups you already have.
-### Step-by-Step: Access Your Backups
+h3. Step-by-Step: Access Your Backups
There are several ways to access your backups.
-- Edit your site within Aegir, and use the `Restore` task. If there
- are multiple backups available, you can select one.
+* Edit your site within Aegir, and use the @Restore@ task. If there
+ are multiple backups available, you can select one.
-- You can access these Aegir backup archives directly, via
- `FTPS/SFTP`
- and `SSH`, at `~/backups/` in your home directory.
+* You can access these Aegir backup archives directly, via @FTPS/SFTP@
+ and @SSH@, at @~/backups/@ in your home directory.
-- If you can't find what you need through an Aegir backup, you have
- further [Idera](r1soft) backups available (see below). You can
- request an
- Idera backup through our [support form](support). (There is no
- direct access to these backups.)
+* If you can't find what you need through an Aegir backup, you have
+ further "Idera":r1soft backups available (see below). You can request an
+ Idera backup through our "support form":support. (There is no
+ direct access to these backups.)
-Task: How to Maintain Your Own Backups
---------------------------------------
+h2. Task: How to Maintain Your Own Backups
-If you prefer to maintain your own backups, use the [**Backup and
-Migrate**](backup-migrate)
+If you prefer to maintain your own backups, use the "*Backup and Migrate*":backup-migrate
module and its "scheduled backups" option.
-### Step-by-Step: Maintain Backups with "Backup and Migrate"
+h3. Step-by-Step: Maintain Backups with "Backup and Migrate"
-- Download the Backup and Migrate module (`backup_migrate`).
+* Download the Backup and Migrate module (@backup_migrate@).
-- Enable the Backup and Migrate module for your site.
+* Enable the Backup and Migrate module for your site.
-- Configure your backups. (Drupal 7:
- `admin/config/system/backup_migrate/`). You can run a *manual*
- backup and/or set up *scheduled* backups. Both kinds will save to
- your site's `private/` directory. Example:
- `sites/foo.com/private/files/backup_migrate/manual/`
+* Configure your backups. (Drupal 7:
+ @admin/config/system/backup_migrate/@). You can run a _manual_
+ backup and/or set up _scheduled_ backups. Both kinds will save to
+ your site's @private/@ directory. Example:
+ @sites/foo.com/private/files/backup_migrate/manual/@
-- Copy these backup archives to your own server or local computer.
- Tools for copying include `SFTP/FTPS` and `rsync` over `SSH`.
+* Copy these backup archives to your own server or local computer.
+ Tools for copying include @SFTP/FTPS@ and @rsync@ over @SSH@.
-- You **must copy all backups before Monday**. Every Monday, we
- **purge**
- all backup archives to keep your Omega8.cc disk space clean.
- Archives are purged from each site's `private/backup_migrate`
- directory, from `~/backups/`, and from anywhere else in your home
- directory. (See below.)
+* You *must copy all backups before Monday*. Every Monday, we *purge*
+ all backup archives to keep your Omega8.cc disk space clean.
+ Archives are purged from each site's @private/backup_migrate@
+ directory, from @~/backups/@, and from anywhere else in your home
+ directory. (See below.)
Fortunately, a week is plenty of time to copy off the files you need.
With enough disk space, you can store all the backups you like.
-More Information
-----------------
+h2. More Information
-### Is There Any Charge for Requesting an Idera Backup?
+h3. Is There Any Charge for Requesting an Idera Backup?
-We are happy to provide an Idera backup to you for **free**, as long as:
+We are happy to provide an Idera backup to you for *free*, as long as:
-- You only make this request occasionally,
+* You only make this request occasionally,
-- and it takes less than 15 minutes of work.
+* and it takes less than 15 minutes of work.
In other cases, this service will cost $152 USD per hour.
-### Are "Backup and Migrate" Backups Protected?
+h3. Are "Backup and Migrate" Backups Protected?
-Yes. On the BOA system, everything under `private/` is inaccessible to
-the public. You must log in with `SSH` or `SFTP/FTPS` to access these
-files.
+Yes. On the BOA system, everything under @private/@ is inaccessible to
+the public. You must log in with @SSH@ or @SFTP/FTPS@ to access these files.
-### How Does Omega8.cc Make Automatic Backups?
+h3. How Does Omega8.cc Make Automatic Backups?
At Omega8.cc, we maintain daily, duplicate, block level (not just file
level) professional backups for all your files and databases, using
-[Idera](r1soft) software.
+"Idera":r1soft software.
We store two copies of these backups:
-- A **local** copy, in the the same facility where your system is
- hosted.
+* A *local* copy, in the the same facility where your system is
+ hosted.
-- A **remote** copy, in a remote facility. The remote backup gives
- you
- extra security.
+* A *remote* copy, in a remote facility. The remote backup gives you
+ extra security.
All backups are versioned and rotated. The backups are rotated daily,
so there is always a copy of all your files from the last 7 days.
-A third, additional copy of your daily **database** backups (not the
+A third, additional copy of your daily *database* backups (not the
files) is also stored on the same local server. These database backups
are rotated weekly, and also archived both locally and remotely.
The result? You always have daily backups of:
-- the last 7 days for your **files**
-- the last 14 days for your **databases**
+* the last 7 days for your *files*
+* the last 14 days for your *databases*
-### How Do Aegir Tasks Make Automatic Backups?
+h3. How Do Aegir Tasks Make Automatic Backups?
Several Aegir tasks generate backups automatically.
-- The `Backup` task, obviously, creates a backup, which you can later
- restore with the `Restore` task.
+* The @Backup@ task, obviously, creates a backup, which you can later
+ restore with the @Restore@ task.
-- When you later `Restore`, Aegir also backs up your *current* site
- before restoring the backup!
+* When you later @Restore@, Aegir also backs up your _current_ site
+ before restoring the backup!
-- `Clone` and `Migrate` also create backups. Even when you only use
- `Migrate` to "Rename" your site by migrating the site to the same
- platform, this task creates a backup.
+* @Clone@ and @Migrate@ also create backups. Even when you only use
+ @Migrate@ to "Rename" your site by migrating the site to the same
+ platform, this task creates a backup.
These backups are compressed archives. Each backup includes:
-- all site files from the `sites/foo.com/` directory
+* all site files from the @sites/foo.com/@ directory
-- a database dump of the site
+* a database dump of the site
-(Note that the backup does *not* include the core code or the modules
-in that site's [platform](platform.))
+(Note that the backup does _not_ include the core code or the modules
+in that site's "platform":platform.)
-### If Your Old Aegir Backups Are Missing
+h3. If Your Old Aegir Backups Are Missing
Aegir makes many automatic backups, and these archives could fill your
disk space very quickly.
-At Omega8.cc, we **purge** the built-in Aegir `~/backups/` directory
-**weekly**, on Monday morning. We also purge each site's private
-`backup_migrate` directory.
+At Omega8.cc, we *purge* the built-in Aegir @~/backups/@ directory
+*weekly*, on Monday morning. We also purge each site's private
+@backup_migrate@ directory.
-If you try to `Restore` an old backup, and it's no longer available,
+If you try to @Restore@ an old backup, and it's no longer available,
don't panic. Remember, you can always request a backup via our
-[support form](support) as long as it is within the last 7 days limit
+"support form":support as long as it is within the last 7 days limit
(or the last 14 days limit for database-only archives).
-Caution
--------
+h2. Caution
Note that you can’t use your Aegir instance disk space as
an archive space. Any files, archives or backups found in your FTPS/SSH
-account home directory, or in `~/static`, or in any other directory
-which is not a part of a valid Drupal multisite (Aegir platform)
-structure
+account home directory, or in @~/static@, or in any other directory
+which is not a part of a valid Drupal multisite (Aegir platform) structure
will be **deleted automatically** once discovered, without any notice,
and we will not accept any related backup recovery requests.
diff --git a/05.advanced/export-site-from-aegir-boa/docs.md b/05.advanced/export-site-from-aegir-boa/docs.md
new file mode 100644
index 0000000..2cd5122
--- /dev/null
+++ b/05.advanced/export-site-from-aegir-boa/docs.md
@@ -0,0 +1,97 @@
+---
+title: TITLE
+slug: URI
+menu: MENU
+date: 08-08-2016
+published: true
+visible: true
+taxonomy:
+ category: docs
+routes:
+ aliases:
+ - /URI
+---
+
+How to Export Your Site From Aegir
+
+You can export any of your Drupal sites from our Hosted Aegir
+environment onto any other host, to another Aegir system or
+as a standalone Drupal site, using the steps outlined below.
+
+h2. Overview
+
+To export your site, you will need three separate "pieces":
+
+* A database dump, saved in the database.sql file
+
+* Everything from the @sites/foo.com/@ directory
+
+* The complete "platform":platform underneath this site
+
+h2. Step-by-Step
+
+*Step 1: Log into the Aegir control panel and run the "Backup" task on your
+site.*
+
+This will create a single, compressed archive in your account
+@~/backups/@ directory. This archive includes the database dump and
+a complete @sites/foo.com/@ directory.
+
+*Step 2: Copy this archive file to your local drive.*
+
+You can use SFTP or FTPS. Or, with rsync over SSH, you can copy
+directly to another server.
+
+*Step 3: Copy the platform directories and files.*
+
+If you've been using your own "custom platform":custom-platform, you
+have full access to all the files, so you can copy them easily.
+
+With our "built-in platforms":built-in-platforms, the best method is
+to use the @rsync@ command. Here is the full command:
+
+
+rsync -avzuL -e ssh user.ftp@host.ip:/path/to/platform /local/path/
+
+
+This command relies on the @-L@ option, so make sure you get those
+options correct.
+
+You must replace the bold *placeholders* with your details:
+
+* Replace @user.ftp@ with your SSH/FTPS account username.
+* Replace @host.ip@ with the domain where you log into Aegir control panel.
+* Use full system paths (see below).
+
+With both the Aegir backup archive from @~/backups/@ and the complete
+platform files, you can import your Drupal site into any other Aegir
+instance. You can also rebuild it as a standalone Drupal site.
+
+h2. Caution
+
+h3. Help! "rsync" Copies All the Other Sites
+
+If you copy a platform with that @rsync@ command, you will copy the
+files of other sites. To avoid this,
+check out the @--exclude@ option for @rsync@. (Run @rsync --help@ for details.)
+
+h3. Don't Use Symlinks in the Path to the Platform
+
+When copying the platform with the @rsync@ command above, you'll need
+to use the full system paths. Don't use relative symlinks that begin
+with @~/platforms@ or @~/clients@ or @~/static@.
+
+You can find the full path to the platform in any of these ways:
+
+* Log into Aegir and check the platform node. This page will include
+ the full path to the platform.
+
+* SSH in, switch to the site directory, and type @drush status@.
+ It will show many details, including the "Drupal root", which is
+ the full path you are looking for.
+
+[platform]link
+
+[custom-platform]http://omega8.cc/how-to-add-custom-platform-properly-140
+
+[built-in-platforms]link
diff --git a/05.advanced/export-site-from-omega8cc/docs.md b/05.advanced/export-site-from-omega8cc/docs.md
deleted file mode 100644
index f8bfba8..0000000
--- a/05.advanced/export-site-from-omega8cc/docs.md
+++ /dev/null
@@ -1,101 +0,0 @@
----
-title: TITLE
-slug: URI
-menu: MENU
-date: 08-08-2016
-published: true
-visible: true
-taxonomy:
- category: docs
-routes:
- aliases:
- - /URI
----
-How to Export Your Site From Aegir
-
-You can export any of your Drupal sites from our Hosted Aegir
-environment onto any other host, to another Aegir system or
-as a standalone Drupal site, using the steps outlined below.
-
-Overview
---------
-
-To export your site, you will need three separate [pieces]()
-
-- A database dump, saved in the database.sql file
-
-- Everything from the `sites/foo.com/` directory
-
-- The complete [platform](platform) underneath this site
-
-Step-by-Step
-------------
-
-*Step 1: Log into the Aegir control panel and run the "Backup" task on
-your
-site.*
-
-This will create a single, compressed archive in your account
-`~/backups/` directory. This archive includes the database dump and
-a complete `sites/foo.com/` directory.
-
-**Step 2: Copy this archive file to your local drive.**
-
-You can use SFTP or FTPS. Or, with rsync over SSH, you can copy
-directly to another server.
-
-**Step 3: Copy the platform directories and files.**
-
-If you've been using your own [custom platform](custom-platform), you
-have full access to all the files, so you can copy them easily.
-
-With our [built-in platforms](built-in-platforms), the best method is
-to use the `rsync` command. Here is the full command:
-
-
-<code>rsync -avzuL -e ssh <strong>user.ftp@host.ip:/path/to/platform /local/path/</strong></code>
-
-This command relies on the `-L` option, so make sure you get those
-options correct.
-
-You must replace the bold **placeholders** with your details:
-
-- Replace `user.ftp` with your SSH/FTPS account username.
-- Replace `host.ip` with the domain where you log into Aegir
- control panel.
-- Use full system paths (see below).
-
-With both the Aegir backup archive from `~/backups/` and the complete
-platform files, you can import your Drupal site into any other Aegir
-instance. You can also rebuild it as a standalone Drupal site.
-
-Caution
--------
-
-### Help! "rsync" Copies All the Other Sites
-
-If you copy a platform with that `rsync` command, you will copy the
-files of other sites. To avoid this,
-check out the `--exclude` option for `rsync`. (Run `rsync --help` for
-details.)
-
-### Don't Use Symlinks in the Path to the Platform
-
-When copying the platform with the `rsync` command above, you'll need
-to use the full system paths. Don't use relative symlinks that begin
-with `~/platforms` or `~/clients` or `~/static`.
-
-You can find the full path to the platform in any of these ways:
-
-- Log into Aegir and check the platform node. This page will include
- the full path to the platform.
-
-- SSH in, switch to the site directory, and type `drush status`.
- It will show many details, including the "Drupal root", which is
- the full path you are looking for.
-
-[platform]link
-
-[custom-platform]http://omega8.cc/how-to-add-custom-platform-properly-140
-
-[built-in-platforms]link
diff --git a/05.advanced/how-edit-settings-php/docs.md b/05.advanced/how-edit-settings-php/docs.md
index 2b0d76a..0faab31 100644
--- a/05.advanced/how-edit-settings-php/docs.md
+++ b/05.advanced/how-edit-settings-php/docs.md
@@ -11,83 +11,73 @@ routes:
aliases:
- /URI
---
+
How to Edit the "settings.php" File on Aegir
-On Aegir, you can't edit `settings.php` directly. Instead, you must
-add your customizations to `local.settings.php`, a file in the same
-directory as `settings.php`.
+On Aegir, you can't edit @settings.php@ directly. Instead, you must
+add your customizations to @local.settings.php@, a file in the same
+directory as @settings.php@.
-Problem
--------
+h2. Problem
-Editing `local.settings.php` is dangerous -- you're basically doing
+Editing @local.settings.php@ is dangerous -- you're basically doing
open-heart surgery on your web site. To avoid accidental mistakes,
Aegir makes you go through a few extra steps every time you want to
-edit `local.settings.php`, which is not writable by default.
+edit @local.settings.php@, which is not writable by default.
-Solution
---------
+h2. Solution
-Here's how to temporarily make `local.settings.php` writable.
+Here's how to temporarily make @local.settings.php@ writable.
-1. Create an empty control file at:
- `sites/foo.com/modules/local-allow.info`
- (`foo.com` is an example -- replace it with your site's real
- domain name).
+# Create an empty control file at: @sites/foo.com/modules/local-allow.info@
+ (@foo.com@ is an example -- replace it with your site's real domain name).
-1. Go to the Aegir control panel and run the "Reset password" task on
- your site. Wait until the task finishes. Now `local.settings.php`
- is
- writable.
+# Go to the Aegir control panel and run the "Reset password" task on
+ your site. Wait until the task finishes. Now @local.settings.php@ is
+ writable.
-1. Edit `local.settings.php` and add your customizations, either on
- the
- command line or via an SFTP or FTPS client and desktop editor.
+# Edit @local.settings.php@ and add your customizations, either on the
+ command line or via an SFTP or FTPS client and desktop editor.
-1. When you're finished, **check your web site**. This is critical.
- Really.
- Even a minor typo in `local.settings.php` can bring down your
- entire web site with a fatal WSOD (White Screen of Death). Log in
- as
- the admin user and make sure the pages are loading properly.
+# When you're finished, *check your web site*. This is critical. Really.
+ Even a minor typo in @local.settings.php@ can bring down your
+ entire web site with a fatal WSOD (White Screen of Death). Log in as
+ the admin user and make sure the pages are loading properly.
-1. When you are certain that your site is not broken, run the "Verify"
- task on your site in the Aegir control panel. This will return
- `local.settings.php` to its safe, unwritable state.
+# When you are certain that your site is not broken, run the "Verify"
+ task on your site in the Aegir control panel. This will return
+ @local.settings.php@ to its safe, unwritable state.
-1. Finally, remove the `local-allow.info` control file. Otherwise, you
- will
- accidentally unprotect `local.settings.php` next time you run
- "Reset
- password."
+# Finally, remove the @local-allow.info@ control file. Otherwise, you will
+ accidentally unprotect @local.settings.php@ next time you run "Reset
+ password."
-Caution
--------
+h2. Caution
-### Help! My Site is Broken And I Can't Fix It!
+h3. Help! My Site is Broken And I Can't Fix It!
-When editing `local.settings.php`, it is possible to break your site
+When editing @local.settings.php@, it is possible to break your site
and be unable to fix it without our help. If you:
-- Edit `local.settings.php` and enter a typo which causes a WSOD,
+* Edit @local.settings.php@ and enter a typo which causes a WSOD,
-- then run "Verify" with a broken `local.settings.php`,
+* then run "Verify" with a broken @local.settings.php@,
-- you will find that your site is broken, and `local.settings.php` is
- unwritable again.
+* you will find that your site is broken, and @local.settings.php@ is
+ unwritable again.
-- If you try to fix things by running "Reset password" to unlock
- `local.settings.php`,
+* If you try to fix things by running "Reset password" to unlock
+ @local.settings.php@,
-- the task will fail, because your site is broken!
+* the task will fail, because your site is broken!
Yes, Aegir will manage to "Verify" your broken site, lock your broken
-`local.settings.php`, and then be unable to *unlock* the very file
+@local.settings.php@, and then be unable to _unlock_ the very file
that's causing the breakage!
The best way to avoid this disaster is to check your site very
carefully before you run "Verify" and thus "save your changes" to
-`local.settings.php`.
+@local.settings.php@.
However, if you do break your site like this, hope is not lost. Open a
-[support ticket](http://omega8.cc/support), and we'll fix things.
+"support ticket":http://omega8.cc/support, and we'll fix things.
diff --git a/05.advanced/migrate-between-installation-profiles/docs.md b/05.advanced/migrate-between-installation-profiles/docs.md
index aa9c68a..0cae1ab 100644
--- a/05.advanced/migrate-between-installation-profiles/docs.md
+++ b/05.advanced/migrate-between-installation-profiles/docs.md
@@ -11,24 +11,23 @@ routes:
aliases:
- /URI
---
+
Migrate Drupal Sites Between Installation Profiles on Aegir
-When you [migrate your Drupal site](migrate-platform) to another
-platform on Aegir, the "Migrate" task does *not* let you pick *any* of
+When you "migrate your Drupal site":migrate-platform to another
+platform on Aegir, the "Migrate" task does _not_ let you pick _any_ of
the available platforms. Instead, you're offered a list of those
-platforms which use the same [installation
-profile](installation-profile)
+platforms which use the same "installation profile":installation-profile
as the current platform.
Normally, this limitation protects you from mistakes. If your site
runs on an Ubercart platform, you don't want to accidentally try to
migrate it to ManagingNews.
-However, what if you *want* to change to a new installation profile?
+However, what if you _want_ to change to a new installation profile?
Read on.
-Why Would You Change Profiles?
-------------------------------
+h2. Why Would You Change Profiles?
For instance, let's say you started a Drupal 6 site on a simple Acquia
installation profile. Later, you decided to add an online store. You
@@ -38,19 +37,18 @@ modules.
Now, you've realized that future upgrades will be simpler and less
error-prone if you run this site on a provided Ubercart platform.
-Use "old_short_name"
-----------------------
+h2. Use "old_short_name"
The problem is, when you try the Aegir "Migrate" task, no Ubercart
platforms appear on the list. For each platform, Aegir checks the
-machine name, defined as `name`. In Drupal 6, an Acquia platform will
-be named `acquia`, while an Ubercart platform will be named
-`uberdrupal`.
+machine name, defined as @name@. In Drupal 6, an Acquia platform will
+be named @acquia@, while an Ubercart platform will be named
+@uberdrupal@.
The solution? On the target platform which you want to move to, set
-`old_short_name` to match the current target. If you want to move from
+@old_short_name@ to match the current target. If you want to move from
Acquia to Ubercart, then on the Ubercart platform, set
-`old_short_name` to `acquia`.
+@old_short_name@ to @acquia@.
Verify the Ubercart platform.
@@ -61,42 +59,41 @@ platforms.
You only have to do this trick once. After this, you'll be migrating
to other Ubercart platforms, so you won't have to worry.
-Where do you set this `old_short_name`? That depends on which major
-version of Drupal you're running.
+Where do you set this @old_short_name@? That depends on which major version of Drupal you're running.
-### Drupal 6: Use a Hook
+h3. Drupal 6: Use a Hook
-In Drupal 6, you use the provided hook, `hook_profile_details()`.
+In Drupal 6, you use the provided hook, @hook_profile_details()@.
-For instance, take a look at the [Open Atrium](http://openatrium.com)
-[installation profile](openatrium-profile). Under
-`openatrium_profile_details()`, they've added this line:
+For instance, take a look at the "Open Atrium":http://openatrium.com
+"installation profile":openatrium-profile. Under
+@openatrium_profile_details()@, they've added this line:
- 'old_short_name' => 'atrium_installer',
+bc. 'old_short_name' => 'atrium_installer',
In fact, we can thank the brilliant folks at
-[Development Seed](http://developmentseed.org)
+ "Development Seed":http://developmentseed.org
for creating this awesome, hidden feature in Aegir precisely because
-of *this* profile. They wanted to change the machine name from
-`atrium_installer` (the `old_short_name`) to `openatrium`.
+of _this_ profile. They wanted to change the machine name from
+@atrium_installer@ (the @old_short_name@) to @openatrium@.
In our Acquia-to-Ubercart example, you would edit the
-`uberdrupal.profile` file on your platform, find the
-`uberdrupal_profile_details()` function, and, under this line:
+@uberdrupal.profile@ file on your platform, find the
+@uberdrupal_profile_details()@ function, and, under this line:
- ‘name’ => ‘UberDrupal’,
+bc. ‘name’ => ‘UberDrupal’,
add this line:
- ‘old_short_name’ => ‘acquia’
+bc. ‘old_short_name’ => ‘acquia’
While you're there, on the target Ubercart platform, remove any other
-profile files in this directory (including the `default` profile, if
+profile files in this directory (including the @default@ profile, if
it exists).
Now, in Aegir, "Verify" the Ubercart platform.
-### Drupal 7: Use the ".info" file
+h3. Drupal 7: Use the ".info" file
!But what if you need to migrate the site between D7 profiles? There
is no hook_profile_details() there, but it is still the same easy,
@@ -105,8 +102,7 @@ Commerce Dev platform when it was using ‘commercedev’ as a machine
name for its installation profile, and you want to migrate it to newer
Commerce 7.x Kickstart platform, but it is using ‘commerce_kickstart’
as a machine name for its installation profile. You only need to add
-one line in your commerce_kickstart.info file, with “old_short_name
-=
+one line in your commerce_kickstart.info file, with “old_short_name =
commercedev” (without quotes), just below “name = Commerce Kickstart”
line. Then re-verify the newer Commerce Kickstart platform in Aegir
and Voilà! – now you can migrate your sites from the old Commerce Dev
diff --git a/05.advanced/open-node-add-access/docs.md b/05.advanced/open-node-add-access/docs.md
index 1d19ab9..75db618 100644
--- a/05.advanced/open-node-add-access/docs.md
+++ b/05.advanced/open-node-add-access/docs.md
@@ -11,40 +11,35 @@ routes:
aliases:
- /URI
---
+
How to Allow "node/add" Anonymous Access
-By default, anonymous visitors cannot access any `node/add` path on a
-site managed with a version of Aegir which comes with [BOA](boa).
+By default, anonymous visitors cannot access any @node/add@ path on a
+site managed with a version of Aegir which comes with "BOA":boa.
-Task: Allow Anonymous "node/add" Access
----------------------------------------
+h2. Task: Allow Anonymous "node/add" Access
However, you can enable anonymous access by
-**creating an empty control file** in the site-specific directory.
-If your domain is `foo.com`, the file would be:
+ *creating an empty control file* in the site-specific directory.
+If your domain is @foo.com@, the file would be:
-`sites/foo.com/modules/allow_anon_node_add.info`
+@sites/foo.com/modules/allow_anon_node_add.info@
-This feature helps if the site's workflow involves the creation of new
-nodes
+This feature helps if the site's workflow involves the creation of new nodes
by visitors who aren't logged in. (This is typical for e-commerce
and community news sites.)
-More Information
-----------------
+h2. More Information
-### Why Is Anonymous "node/add" Access Blocked?
+h3. Why Is Anonymous "node/add" Access Blocked?
-A page with a `node/add` path is never cached, so Drupal has to
-rebuild the page on-the-fly on every request. Any page that Drupal
-builds
-like that is a risk for a brute-force Denial of Service attack. An
-attacker
+A page with a @node/add@ path is never cached, so Drupal has to
+rebuild the page on-the-fly on every request. Any page that Drupal builds
+like that is a risk for a brute-force Denial of Service attack. An attacker
could bring your site down by accessing these pages with hundreds or
thousands of hits in a very short time.
-Thus, the default [BOA](boa) protection is to restrict `node/add` access
-to
+Thus, the default "BOA":boa protection is to restrict @node/add@ access to
logged-in users. Most workflows require that a user log in before
adding a node, so this system usually works fine.
diff --git a/05.advanced/shell-ftps-extra-accounts/docs.md b/05.advanced/shell-ftps-extra-accounts/docs.md
index a09de3c..7ecd08e 100644
--- a/05.advanced/shell-ftps-extra-accounts/docs.md
+++ b/05.advanced/shell-ftps-extra-accounts/docs.md
@@ -11,77 +11,74 @@ routes:
aliases:
- /URI
---
+
Aegir Clients: Adding SSH/FTPS Users to Your Drupal Sites
One of the great strengths of Aegir is that you get the power to
manage all your Drupal sites in one place. But what if you need to let
-another user access *some* of the sites? The solution is simple: add
-an Aegir **client**.
+another user access _some_ of the sites? The solution is simple: add
+an Aegir *client*.
-What Can an Aegir Client Do?
-----------------------------
+h2. What Can an Aegir Client Do?
-An Aegir client can access and manage one or more sites, and *only*
+An Aegir client can access and manage one or more sites, and _only_
those sites. You, the admin, control which sites each client can
access. All other sites remain completely hidden from that client.
This management has two aspects:
-- Managing sites via the **Aegir control panel**, running
- Aegir tasks like "Backup", "Migrate", and so on.
+* Managing sites via the *Aegir control panel*, running
+Aegir tasks like "Backup", "Migrate", and so on.
-- Using **SSH** (a [limited Secure Shell](limited-shell)) or **FTPS**
- (FTP over SSL) to
- access files and run `drush`.
+* Using *SSH* (a "limited Secure Shell":limited-shell) or *FTPS* (FTP over SSL) to
+ access files and run @drush@.
-What Can't an Aegir Client Do?
-------------------------------
+h2. What Can't an Aegir Client Do?
An Aegir client can't access any sites that it doesn't own. A client
always moves and acts within a particular site or sites.
This means that an Aegir client also can't work at the higher level of
-Aegir [platforms](platform). Only an admin can work with platforms.
+Aegir "platforms":platform. Only an admin can work with platforms.
How does Aegir enforce these restrictions?
When someone logs into the Aegir panel as a client (technically, as
-we'll see in a moment, a *user* with only the "aegir client" role), he
+we'll see in a moment, a _user_ with only the "aegir client" role), he
or she only sees the sites owned by this client. The other sites don't
appear, and neither does the "Platforms" menu tab.
When this person uses SSH with the client credentials, he or she lands
-in a sparse "home" directory with one visible symbolic link: `sites/`.
-And `sites/` shows only the directories for the sites which this
-client owns. As a client, you'll never see `sites/all/`, only the
-`sites/foo.com/` directory for each site.
+in a sparse "home" directory with one visible symbolic link: @sites/@.
+And @sites/@ shows only the directories for the sites which this
+client owns. As a client, you'll never see @sites/all/@, only the
+@sites/foo.com/@ directory for each site.
These restrictions protect the other sites on the platform. If a
person makes mistakes, they're confined to the sites owned by this
client.
-The "User" and the "Client"
----------------------------
+h2. The "User" and the "Client"
Adding an Aegir client is easy, but you need to understand that you're
-really adding two, *separate* things: an Aegir *user* and an SSH/FTPS
-*client*.
+really adding two, _separate_ things: an Aegir _user_ and an SSH/FTPS
+_client_.
-The *user* can log in to Aegir and run Aegir tasks. An Aegir user
+The _user_ can log in to Aegir and run Aegir tasks. An Aegir user
basically feels like a Drupal user. You change the password on the
"Edit account" page, users have roles, users can be blocked, and so
on.
-The actual *client* can use SSH or FTPS. An Aegir client is very
+The actual _client_ can use SSH or FTPS. An Aegir client is very
different from a Drupal user; it is unique to Aegir. A client is
basically a username and password, and Aegir generates this password
automatically (see below).
-### Many Users, One Client?
+h3. Many Users, One Client?
When you create a client in Aegir, Aegir tries to keep things simple
by automatically creating both the client and an associated user with
-the same `Internal name` and the (aptly named) "aegir client" role. If
+the same @Internal name@ and the (aptly named) "aegir client" role. If
you just need to let someone access a site, this will work fine.
However, because these things are separate, you have options. You can
@@ -94,37 +91,36 @@ On the other hand, if a single user needs access to multiple clusters
of sites, you can associate multiple clients to that user (see below).
Even if you never plan to use this complexity, you need to understand
-this difference between *user* and *client* so that you don't get
+this difference between _user_ and _client_ so that you don't get
confused.
-### Manage "Clients"?
+h3. Manage "Clients"?
For instance, when you click "Manage Clients" in the Administration
-menu, you're actually taken to a listing of Drupal *users*, not
+menu, you're actually taken to a listing of Drupal _users_, not
clients.
Aegir does not currently provide a page where you can view a list of
-clients. However, when you edit a site's `Client` field (see below),
+clients. However, when you edit a site's @Client@ field (see below),
and begin to type a client name, Drupal will attempt to finish it with
autocomplete.
-How to Add an Aegir Client on Omega8cc
---------------------------------------
+h2. How to Add an Aegir Client on Omega8cc
The concepts may be complex, but actually adding a client is easy. On
the Aegir admin panel, look at the "Administration" menu in the bottom
right. Click "Add Client".
-Enter the human-readable `Client name`, the machine-readable `Internal
-name` (no spaces or metacharacters), and the `Email address` (twice).
+Enter the human-readable @Client name@, the machine-readable @Internal
+name@ (no spaces or metacharacters), and the @Email address@ (twice).
-Technically, you can leave the `Internal name` blank and let Aegir
-generate it from the `Client name`.
+Technically, you can leave the @Internal name@ blank and let Aegir
+generate it from the @Client name@.
-### Include an Email to Also Create a User
+h3. Include an Email to Also Create a User
-What about the email? If you leave the email blank, Aegir will *not*
-create an Aegir control panel user, but *will* create the SSH/FTPS
+What about the email? If you leave the email blank, Aegir will _not_
+create an Aegir control panel user, but _will_ create the SSH/FTPS
client. (This client is only created if you're on an Octopus Satellite
Instance, such as your Omega8cc account.)
@@ -135,55 +131,53 @@ If you think about it (for awhile), this actually makes sense. The
Aegir user corresponds to a human being, while the client is more of a
set of credentials. Only humans have email addresses.
-Let Clients Own Your Sites
---------------------------
+h2. Let Clients Own Your Sites
Now that you have a client, it's time to own some sites. This is easy
too.
-Edit the site node. ("Add Sites" -> click your site in the listing
-->
+Edit the site node. ("Add Sites" -> click your site in the listing ->
"Edit".)
-Enter your client in the `Client` field. The default owner is `Aegir`.
+Enter your client in the @Client@ field. The default owner is @Aegir@.
Start to type the client name, and Drupal should autocomplete it.
-**Never leave `Client` blank.** If you could do this, *all* users would
-have access to the site in the Aegir admin panels! Fortunately, you
-can't. Aegir will prevent you from saving the site with no client,
-or an invalid client name.
+ *Never leave @Client@ blank.* If you could do this, _all_ users would
+ have access to the site in the Aegir admin panels! Fortunately, you
+ can't. Aegir will prevent you from saving the site with no client,
+ or an invalid client name.
When you save the site node, Aegir will run the Verify task.
-### Find the Client Password
+h3. Find the Client Password
As the site is verified, Aegir generates a new password for this
-client. The new password is placed in a file in `~/users/`.
+client. The new password is placed in a file in @~/users/@.
The name of this file is also important: it's the actual SSH/FTPS
-username for this client. This username is the `Internal name` you
+username for this client. This username is the @Internal name@ you
entered for this client, prepended by a seemingly random string, which
you'll quickly recognize as your beloved Omega8cc user ID.
Don't forget to actually send this username and password to whoever
will need it.
-### Change the Client Password
+h3. Change the Client Password
If you ever need to change the password, just delete this file in
-`~/users/`. Within five minutes, Aegir will generate a new file with a
+@~/users/@. Within five minutes, Aegir will generate a new file with a
new password.
-Remember, the Aegir users are separate from the clients. *Users* can
+Remember, the Aegir users are separate from the clients. _Users_ can
change their own passwords as they would in Drupal, on their own "Edit
account" pages.
-### Deleting a Client
+h3. Deleting a Client
What if you want to remove a client entirely? Edit each site this
-client owns, and set `Client` to another client, or back to "Aegir".
+client owns, and set @Client@ to another client, or back to "Aegir".
-### Owners and Users
+h3. Owners and Users
An Aegir site can have only one owner. (Of course, users with the
"admin" role can still access any site.)
@@ -196,7 +190,7 @@ Or, if you need one person to access multiple clusters of sites, that
single user can be associated with multiple clients.
To add or remove clients from a user, click "Manage clients" in the
-lower-right Administration menu, find the username, and click `edit`
+lower-right Administration menu, find the username, and click @edit@
on that row. Below the expected email and password fields, you'll see
"Associate a client to this user." It's another autocomplete field;
just start typing the client field.
@@ -208,33 +202,29 @@ Don't forget that a single client can own multiple sites. This makes
it easy to manage a cluster of sites that belong to a particular
person or group.
-Final Tips on Aegir Clients
----------------------------
+h2. Final Tips on Aegir Clients
A few more notes and potential gotchas:
-- Client accounts *cannot* use SFTP (FTP over SSH), for security
- reasons.
+* Client accounts _cannot_ use SFTP (FTP over SSH), for security
+ reasons.
-- If you use FTPS (FTP over SSL), set "Explicit TLS mode" and port 21
+* If you use FTPS (FTP over SSL), set "Explicit TLS mode" and port 21
in your FTPS software.
-- Client SSH accounts have `drush` enabled by default.
+* Client SSH accounts have @drush@ enabled by default.
-- When people use clients to manage site files, they should remember
- to [set group writable permissions](group-writable) to any files
- they upload with
- `chmod 775`.
+* When people use clients to manage site files, they should remember
+ to "set group writable permissions":group-writable to any files they upload with
+ @chmod 775@.
-- All files and directories in all sites are reset to be owned by
- your
- main SSH account every morning.
+* All files and directories in all sites are reset to be owned by your
+ main SSH account every morning.
-- Remember, clients cannot access platforms. If you need multiple
- developers to have a higher level of access, consider creating
- (when
- self-hosted) or purchasing (when hosted) separate Octopus/Aegir
- instances.
+* Remember, clients cannot access platforms. If you need multiple
+developers to have a higher level of access, consider creating (when
+self-hosted) or purchasing (when hosted) separate Octopus/Aegir
+instances.
[drush]link
diff --git a/06.troubleshooting/aegir-task-fails-spins/docs.md b/06.troubleshooting/aegir-task-fails-spins/docs.md
index b9d06ad..78efd4d 100644
--- a/06.troubleshooting/aegir-task-fails-spins/docs.md
+++ b/06.troubleshooting/aegir-task-fails-spins/docs.md
@@ -11,6 +11,7 @@ routes:
aliases:
- /URI
---
+
Aegir Task Fails or Spins Forever
Sometimes an Aegir task will fail or keep running ("spinning") as if
@@ -18,168 +19,147 @@ it will never stop. Don't panic; you can often work around these
broken tasks.
You may be able to delete a task, or even a site or platform node
-(not the site or platform itself!), by visiting the correct **path**
+(not the site or platform itself!), by visiting the correct *path*
to a delete page within Aegir control panel.
-Task: Delete a Site/Platform Node Manually
-------------------------------------------
+h2. Task: Delete a Site/Platform Node Manually
-You want to delete a site or platform, but the Aegir `Delete` task
+You want to delete a site or platform, but the Aegir @Delete@ task
fails. Now what?
-1. A word of warning: never, ever attempt to delete the site or
- platform
- files and directories manually via SFTP, FTPS or [SSH](ssh) -- you
- will
- only make things (much) worse to clean up. You should always allow
- Aegir to delete the site (or platform) by running the `Delete`
- task,
- even if it will eventually fail.
+# A word of warning: never, ever attempt to delete the site or platform
+ files and directories manually via SFTP, FTPS or "SSH":ssh -- you will
+ only make things (much) worse to clean up. You should always allow
+ Aegir to delete the site (or platform) by running the @Delete@ task,
+ even if it will eventually fail.
-1. First, `View` the details (a log) of why the `Delete` task failed.
- Try to debug the failure. Once you delete the site or platform node
- in the Aegir control panel, you'll also delete all associated task
- nodes,
- and you'll lose the option to restore from any existing Aegir
- backups
- of the site. So be sure you can accept these side effects before
- you proceed.
+# First, @View@ the details (a log) of why the @Delete@ task failed.
+ Try to debug the failure. Once you delete the site or platform node
+ in the Aegir control panel, you'll also delete all associated task nodes,
+ and you'll lose the option to restore from any existing Aegir backups
+ of the site. So be sure you can accept these side effects before you proceed.
-1. Click the `Edit` tab for the site or platform.
+# Click the @Edit@ tab for the site or platform.
-1. In the URL for this edit page, replace `edit` with `delete`. If the
- path ends in `node/123/edit`, change it to `node/123/delete`.
+# In the URL for this edit page, replace @edit@ with @delete@. If the
+ path ends in @node/123/edit@, change it to @node/123/delete@.
-1. Press `ENTER` to visit the new URL you've typed.
+# Press @ENTER@ to visit the new URL you've typed.
-1. On this delete page, click `Delete`, and confirm.
+# On this delete page, click @Delete@, and confirm.
This should delete the site's or platform's node in Aegir (not the site
or platform on the filesystem, obviously).
-Note that the '`View` task log' hint is useful only for already failed
-and
-not still running ("spinning forever") tasks, because when the task is
-still
+Note that the '@View@ task log' hint is useful only for already failed and
+not still running ("spinning forever") tasks, because when the task is still
in the pseudo-running state, its log will be mostly empty or incomplete.
-Remember that you have just deleted only a record in the Aegir control
-panel,
+Remember that you have just deleted only a record in the Aegir control panel,
while the site or the platform may still exist on the filesystem.
It is theoretically possible to fix the source of the initial problem
and then add the platform in Aegir again,
or else re-Verify site's platform to re-discover the now hidden site.
If the
-leftovers on the system are incompletely removed after the failed
-`Delete` task,
-you should [contact support](support) for assistance.
+leftovers on the system are incompletely removed after the failed @Delete@ task,
+you should "contact support":support for assistance.
-Task: Delete a Task Node That's "Spinning Forever"
---------------------------------------------------
+h2. Task: Delete a Task Node That's "Spinning Forever"
You can stop any task by manually deleting its node.
-Note: `Clone` or `Migrate` tasks will require extra attention (see
-below).
+Note: @Clone@ or @Migrate@ tasks will require extra attention (see below).
-1. Make sure you wait at least **15-30 minutes** before manually
- deleting a task node.
- There are heavy distros like the new Open Atrium 2.0 where even the
- initial
- site install may take longer than 10 minutes to complete.
+# Make sure you wait at least *15-30 minutes* before manually deleting a task node.
+ There are heavy distros like the new Open Atrium 2.0 where even the initial
+ site install may take longer than 10 minutes to complete.
-1. Right-click on the `View` link of the “spinning” task and select
- `Open in New Window` or `New Tab`. This brings you to the node for
- this task.
+# Right-click on the @View@ link of the “spinning” task and select
+ @Open in New Window@ or @New Tab@. This brings you to the node for this task.
-1. Click on the `Edit` tab of the task node.
+# Click on the @Edit@ tab of the task node.
-1. In the URL, replace `edit` with `delete`. If the URL is
- `node/123/edit`, change it to `node/123/delete`.
+# In the URL, replace @edit@ with @delete@. If the URL is
+ @node/123/edit@, change it to @node/123/delete@.
-1. Press `ENTER` to visit the new URL you've typed.
+# Press @ENTER@ to visit the new URL you've typed.
-1. On this delete page, confirm the deletion.
+# On this delete page, confirm the deletion.
-1. If the task was running on a site, `Verify` the platform where the
- site is (or should be). Aegir will re-discover and `Verify` the
- site, which will generate a new node for the site.
+# If the task was running on a site, @Verify@ the platform where the
+ site is (or should be). Aegir will re-discover and @Verify@ the
+ site, which will generate a new node for the site.
-Task: Fix a Broken "Clone" or "Migrate" Task
---------------------------------------------
+h2. Task: Fix a Broken "Clone" or "Migrate" Task
-When a `Clone` or `Migrate` task times out, it may have actually moved
+When a @Clone@ or @Migrate@ task times out, it may have actually moved
or created the site as instructed.
-But if the `Clone` or `Migrate` task is still spinning in your task
+But if the @Clone@ or @Migrate@ task is still spinning in your task
queue, you need to delete this task manually, otherwise the task queue
will stay locked up forever.
-1. Make sure the site was actually migrated or cloned. Check the
- filesystem via SFTP or SSH and see whether the new directories are
- present on the correct platform.
+# Make sure the site was actually migrated or cloned. Check the
+ filesystem via SFTP or SSH and see whether the new directories are
+ present on the correct platform.
-1. Delete the **site node** for the migrated or cloned site. Do **not**
- use
- the `Delete` task! Instead, follow the steps given above for
- deleting a site node manually. (See below for why you must delete
- this site node.)
+# Delete the *site node* for the migrated or cloned site. Do *not* use
+ the @Delete@ task! Instead, follow the steps given above for
+ deleting a site node manually. (See below for why you must delete
+ this site node.)
-1. Delete the **task node** for the spinning `Clone` or `Migrate`
- task. Follow the steps given above for deleting a task node.
+# Delete the *task node* for the spinning @Clone@ or @Migrate@
+ task. Follow the steps given above for deleting a task node.
-1. When you verify the platform, Aegir should discover your new cloned
- or migrated site.
+# When you verify the platform, Aegir should discover your new cloned
+ or migrated site.
-Task: Fix the Huge "files/" Problem
------------------------------------
+h2. Task: Fix the Huge "files/" Problem
-If your site has a large `files/` directory, your `Clone`, `Migrate`,
-and `Backup` tasks will take a long time, or even fail.
+If your site has a large @files/@ directory, your @Clone@, @Migrate@,
+and @Backup@ tasks will take a long time, or even fail.
-Aegir creates a full, compressed archive of `sites/foo.com/`, and a
-large `sites/foo.com/files/` directory can make this task exceed the
+Aegir creates a full, compressed archive of @sites/foo.com/@, and a
+large @sites/foo.com/files/@ directory can make this task exceed the
server limit.
-The solution is to use a **symbolic link** (symlink), so that these
-tasks copy only a symlink and not the actual `files/` directory.
+The solution is to use a *symbolic link* (symlink), so that these
+tasks copy only a symlink and not the actual @files/@ directory.
How large is 'too large'? It depends on the system power and load,
-but it is safe to assume that any site with the `files/` directory
+but it is safe to assume that any site with the @files/@ directory
larger than 1-2 GB should have that directory symlinked.
-Please [contact support](support) to request that we solve this for you.
+Please "contact support":support to request that we solve this for you.
-**WARNING:** You'll need to **maintain your own backup** of your
-`files/`
+*WARNING:* You'll need to *maintain your own backup* of your @files/@
directory now, since Aegir backups will only contain a symlink.
Of course, our Idera backups will still contain all your files,
no matter where in your account they were moved and symlinked.
-More Information
-----------------
+h2. More Information
-### Is a "Spinning" Task Always Still Running?
+h3. Is a "Spinning" Task Always Still Running?
No. When a task seems to keep "spinning forever," it may mean that the
task isn't actually running, but has timed out in the Aegir
backend. If the backend failed to report failure (or success!) to the
frontend, the task will still appear to run.
-### Why Delete the Site Node for a Stuck "Clone" or "Migrate"?
+h3. Why Delete the Site Node for a Stuck "Clone" or "Migrate"?
-If a `Clone` or `Migrate` task times out and won't stop spinning,
+If a @Clone@ or @Migrate@ task times out and won't stop spinning,
Aegir is out-of-date; for this cloned or migrated site, Aegir may
-still be storing the **old location** on the wrong platform.
+still be storing the *old location* on the wrong platform.
-After you delete this broken site node, you will `Verify` the
+After you delete this broken site node, you will @Verify@ the
platform, and Aegir will discover the "new" site.
If you don't delete the broken site node, Aegir will refuse to add
the new site because it has the same domain as the broken site
node.
-But Aegir will *also* fail to verify this broken site node in the old
+But Aegir will _also_ fail to verify this broken site node in the old
platform, because the site is no longer there in the filesystem.
Thus, you have to delete the site node manually.
diff --git a/06.troubleshooting/chapter.md b/06.troubleshooting/chapter.md
index ca1de2d..2fa8d27 100644
--- a/06.troubleshooting/chapter.md
+++ b/06.troubleshooting/chapter.md
@@ -12,4 +12,4 @@ taxonomy:
# Troubleshooting
-Learn how to resolve common problems with Aegir BOA hosting for Drupal.
+Learn how to resolve and avoid common problems with Aegir BOA hosting for Drupal.
diff --git a/06.troubleshooting/debug-wsod/docs.md b/06.troubleshooting/debug-wsod/docs.md
index 47d6e99..25f7799 100644
--- a/06.troubleshooting/debug-wsod/docs.md
+++ b/06.troubleshooting/debug-wsod/docs.md
@@ -11,89 +11,79 @@ routes:
aliases:
- /URI
---
+
How to Debug WSOD and Other Errors?
When your Drupal site comes up blank, you need to debug this White
Screen of Death (WSOD). But without root access, you can't access the
-server logs. The solution is to *temporarily* show the errors
+server logs. The solution is to _temporarily_ show the errors
onscreen.
-Task: Show Errors for Debugging
--------------------------------
+h2. Task: Show Errors for Debugging
-1. On the Aegir control panel screen for your site, click the
- `Edit` tab.
+# On the Aegir control panel screen for your site, click the @Edit@ tab.
-1. Add an alias for the site which includes `.dev.` or `.devel.`. For
- instance, if your site is `foo.com`, you can do
- `bar.devel.foo.com`. Note that you need *both* periods, before and
- after the `.dev.` or `.devel.`. Don't [rename](rename-task) the
- site,
- just add an [alias](manage-aliases-redirects).
+# Add an alias for the site which includes @.dev.@ or @.devel.@. For
+ instance, if your site is @foo.com@, you can do
+ @bar.devel.foo.com@. Note that you need _both_ periods, before and
+ after the @.dev.@ or @.devel.@. Don't "rename":rename-task the site,
+ just add an "alias":manage-aliases-redirects.
-1. Wait for the Verify task to complete.
+# Wait for the Verify task to complete.
-1. Access your site using just added dev alias. You should now see PHP
- errors.
- (If not, see below.)
+# Access your site using just added dev alias. You should now see PHP errors.
+ (If not, see below.)
-1. Use these errors to debug and fix your code.
+# Use these errors to debug and fix your code.
-1. When your site is working again, edit the site in Aegir and
- *delete
- this alias*. It's a security risk to leave it available for
- prying eyes.
+# When your site is working again, edit the site in Aegir and *delete
+ this alias*. It's a security risk to leave it available for prying eyes.
-More Information
-----------------
+h2. More Information
-### Why Are the ".dev." and ".devel." Aliases a Security Risk?
+h3. Why Are the ".dev." and ".devel." Aliases a Security Risk?
The PHP errors could reveal security vulnerabilities on your web site.
You should always delete these aliases as soon as you have finished
debugging and gotten your site working again.
-### What If No Errors Appear?
+h3. What If No Errors Appear?
-If you still get a blank WSOD with a `.dev.` or `.devel.` alias, there
+If you still get a blank WSOD with a @.dev.@ or @.devel.@ alias, there
are several possible problems:
-- A PHP file in a module or theme may be truncated or incomplete.
+* A PHP file in a module or theme may be truncated or incomplete.
-- You forgot to **clear the caches** after a code update. Here, the
- problem is at the database level, not PHP. Try these Aegir tasks:
- `Flush all caches`, and if that doesn't work, `Rebuild
- registry`. (In drush, these are `drush cc all` and `drush rr`.)
+* You forgot to *clear the caches* after a code update. Here, the
+ problem is at the database level, not PHP. Try these Aegir tasks:
+ @Flush all caches@, and if that doesn't work, @Rebuild
+ registry@. (In drush, these are @drush cc all@ and @drush rr@.)
-### Why Are Two Periods Needed With ".dev." and ".devel."?
+h3. Why Are Two Periods Needed With ".dev." and ".devel."?
Previously, you did not need an initial period, but this led to
-problems for domains like `mydev.com`, so now both periods are
-required. The exception is a domain which *begins* with `dev.`; so,
-`dev.foo.com` will still work. See [this bug
-report.](https://drupal.org/node/2015551#comment-7648111)
+problems for domains like @mydev.com@, so now both periods are
+required. The exception is a domain which _begins_ with @dev.@; so,
+@dev.foo.com@ will still work. See "this bug report.":https://drupal.org/node/2015551#comment-7648111
-### If ".dev." Works, But Main Domain Still Breaks?
+h3. If ".dev." Works, But Main Domain Still Breaks?
-What if you fix everything with your `.dev.` alias, and the site loads
+What if you fix everything with your @.dev.@ alias, and the site loads
perfectly, but the main domain still breaks with a WSOD?
-You can usually solve this by **clearing all caches**. Use the Aegir
-task `Flush all caches` or run `drush cc all` on the command line.
+You can usually solve this by *clearing all caches*. Use the Aegir
+task @Flush all caches@ or run @drush cc all@ on the command line.
If this doesn't work, the problem could be related to our Redis
caching. Wait a day to see whether the daily restart fixes things.
-Until this restart happens, [**disable Redis caching** temporarily with
-these instructions](cache-redis).
+Until this restart happens, "*disable Redis caching* temporarily with these instructions":cache-redis.
Remember to re-enable Redis once the issue is gone.
Finally, check whether you added any contrib modules before the WSOD.
A new module, or a recently configured module, is a likely culprit.
-References
-----------
-
-- [How to Disable all Caching and Aggregation](cache-disable-all)
+h2. References
-- [Using Redis Caching](cache-redis)
+* "How to Disable all Caching and Aggregation":cache-disable-all
+* "Using Redis Caching":cache-redis
diff --git a/06.troubleshooting/firewall-ip-blocked/docs.md b/06.troubleshooting/firewall-ip-blocked/docs.md
index ba51956..cf070fe 100644
--- a/06.troubleshooting/firewall-ip-blocked/docs.md
+++ b/06.troubleshooting/firewall-ip-blocked/docs.md
@@ -11,114 +11,95 @@ routes:
aliases:
- /URI
---
+
Is the Aegir Firewall Blocking Your IP?
-Our [BOA](boa) servers include a pro-active, autonomous firewall,
+Our "BOA":boa servers include a pro-active, autonomous firewall,
which can block your IP address if any of defined security thresholds
are exceeded from your IP. If your site appears to be down,
follow these steps to check whether it's just your IP being blocked.
-Task: Unblock Your IP
----------------------
+h2. Task: Unblock Your IP
-1. Check our [Network Status](omega8cc-network) and [Scheduled
- Maintenance](omega8cc-maintenance)
- pages to check if there is any scheduled maintenance running
- or any known network incident reported.
+# Check our "Network Status":omega8cc-network and "Scheduled Maintenance":omega8cc-maintenance
+ pages to check if there is any scheduled maintenance running
+ or any known network incident reported.
-1. If not, or if you can't access our web site, check our official
- [Omega8cc Twitter Timeline](omega8cc-twitter) for any
- outage reported.
+# If not, or if you can't access our web site, check our official
+ "Omega8cc Twitter Timeline":omega8cc-twitter for any outage reported.
-1. If no outage is reported, check if your HTTP entry gateway is online
- on our
- [Pingdom Status Page](omega8cc-uptime). Your Aegir control panel
- URL
- probably includes a name of one of the gateways monitored there,
- so it should be easy to identify.
+# If no outage is reported, check if your HTTP entry gateway is online on our
+ "Pingdom Status Page":omega8cc-uptime. Your Aegir control panel URL
+ probably includes a name of one of the gateways monitored there,
+ so it should be easy to identify.
-1. If there is still no information about any outage, try to access
- your site
- through another IP. For instance, use your mobile phone, or a third
- party
- monitoring service. We use [Pingdom](http://pingdom.com). For a
- quick, free check,
- try [isup.me](http://isup.me).
+# If there is still no information about any outage, try to access your site
+ through another IP. For instance, use your mobile phone, or a third party
+ monitoring service. We use "Pingdom":http://pingdom.com. For a quick, free check,
+ try "isup.me":http://isup.me.
-1. If the site works elsewhere, your IP must be blocked. Wait one hour.
+# If the site works elsewhere, your IP must be blocked. Wait one hour.
-1. If your IP is still blocked after an hour, [contact
- support](support)
- and we'll remove the block and provide more details on the specific
- reason of the block.
+# If your IP is still blocked after an hour, "contact support":support
+ and we'll remove the block and provide more details on the specific
+ reason of the block.
-Task: Temporarily Whitelist Your IP
------------------------------------
+h2. Task: Temporarily Whitelist Your IP
If more than one person is working on the same server from the same
IP address, and there is essentially no other traffic on this
-instance (which should normally be unusual), this can trigger an IP
-block.
+instance (which should normally be unusual), this can trigger an IP block.
You can temporarily whitelist your IP address via SSH authentication,
assuming you are not blocked already:
-1. Log in with `ssh`.
+# Log in with @ssh@.
-1. Run `ping -t 10 foo.com`, where `foo.com` is any remote site domain
- or server IP that will respond to `ping`, but is not hosted on our
- network.
- If you don't keep the session active, the server will disconnect
- you
- after 15 minutes of inactivity.
+# Run @ping -t 10 foo.com@, where @foo.com@ is any remote site domain
+ or server IP that will respond to @ping@, but is not hosted on our network.
+ If you don't keep the session active, the server will disconnect you
+ after 15 minutes of inactivity.
-Your IP will remain whitelisted as long as the session is active. This
-is
+Your IP will remain whitelisted as long as the session is active. This is
not a full whitelisting--you can still get blocked (see the list of
triggers below). But this will increase the allowed HTTP requests
threshold, to avoid unintended self-blocking from working on the site.
-More Information
-----------------
+h2. More Information
-### How Does Your IP Get Blocked?
+h3. How Does Your IP Get Blocked?
Your IP can get blocked by the firewall in several ways:
-- Too many **failed SSH or FTPS** log-in attempts.
+* Too many *failed SSH or FTPS* log-in attempts.
-- A constant (not just quick and accidental) **port scan**. These port
- scans
- can be unintentional and caused by unrelated software, such as
- your email client, trying to connect to an unavailable service or
- port.
- Make sure it is not your Wi-Fi connected mobile phone with old
- mail server settings; this setup will keep blocking you.
+* A constant (not just quick and accidental) *port scan*. These port scans
+ can be unintentional and caused by unrelated software, such as
+ your email client, trying to connect to an unavailable service or port.
+ Make sure it is not your Wi-Fi connected mobile phone with old
+ mail server settings; this setup will keep blocking you.
-- Too many incoming ping/ICMP requests. Our servers don't respond to
- these requests. If you flood-ping us, your IP address will be
- blocked,
- first temporarily, and after a few temporary blocks, permanently.
+* Too many incoming ping/ICMP requests. Our servers don't respond to
+ these requests. If you flood-ping us, your IP address will be blocked,
+ first temporarily, and after a few temporary blocks, permanently.
-- A pseudo-DoS (Denial of Service) attack, like an attempt to crawl
- the sites with HTTrack or to benchmark the site with Apache Bench.
+* A pseudo-DoS (Denial of Service) attack, like an attempt to crawl
+ the sites with HTTrack or to benchmark the site with Apache Bench.
-- If your site causes a redirect loop, that can trigger an IP block
- because of the flood of DoS-like HTTP requests.
+* If your site causes a redirect loop, that can trigger an IP block
+ because of the flood of DoS-like HTTP requests.
-- More than one person working on the same server from the same IP
- address, with essentially no other traffic on this instance
- (see above).
+* More than one person working on the same server from the same IP
+ address, with essentially no other traffic on this instance (see above).
-- Flooding the server with HTTP POST requests that are never cached.
+* Flooding the server with HTTP POST requests that are never cached.
-### How Should You Monitor Your Server Uptime?
+h3. How Should You Monitor Your Server Uptime?
-Do not use `ping` or port scans with `telnet` to test your server
+Do not use @ping@ or port scans with @telnet@ to test your server
uptime. Your IP will get blocked.
-Instead, use `curl -I foo.com` requests or a service like
-[Pingdom](http://pingdom.com).
+Instead, use @curl -I foo.com@ requests or a service like "Pingdom":http://pingdom.com.
[boa]
[omega8cc-twitter]
diff --git a/06.troubleshooting/recipes-for-disaster/docs.md b/06.troubleshooting/recipes-for-disaster/docs.md
index 3e38fc2..8507ad4 100644
--- a/06.troubleshooting/recipes-for-disaster/docs.md
+++ b/06.troubleshooting/recipes-for-disaster/docs.md
@@ -11,170 +11,161 @@ routes:
aliases:
- /URI
---
+
Avoid Disaster on Your Aegir Sites
We've tried hard to make Aegir on BOA as foolproof and fear-free as
possible. But if you jump in and start clicking before you know what
you're doing, you can still cause serious problems. We strongly urge
-you to read our short series of articles on [Aegir
-basics](aegir-basics).
+you to read our short series of articles on "Aegir basics":aegir-basics.
But at a bare minimum, at least take a few minutes here and learn
how to avoid these potential disasters.
-"Restore" Can't Always Save You
--------------------------------
+h2. "Restore" Can't Always Save You
-Many Aegir tasks create [automatic backups](aegir-backups), so that you
-can use the `Restore` task if anything goes wrong.
+Many Aegir tasks create "automatic backups":aegir-backups, so that you
+can use the @Restore@ task if anything goes wrong.
However, if you don't follow the correct upgrade workflow and
-[good habits](good-habits), you can get stuck with a broken site that
-`Restore` won't fix.
+"good habits":good-habits, you can get stuck with a broken site that @Restore@ won't fix.
Let's say you want to make a new platform, with upgraded modules. You
upload the upgraded modules to your new platform. Then you use the
-`Backup` task. All good so far.
+@Backup@ task. All good so far.
-The correct next step is to `Clone` your site, on the *current
-platform*, and then `Migrate` the *clone* to the new platform. If one
+The correct next step is to @Clone@ your site, on the *current
+platform*, and then @Migrate@ the _clone_ to the new platform. If one
of those upgraded modules turns out to break the clone, your live site
remains safe on the old platform.
The disastrous, mistaken next step is to skip the time-consuming clone
-and `Migrate` your live site directly to the new platform *without*
+and @Migrate@ your live site directly to the new platform _without_
testing a clone first. You foolishly trust that, if anything breaks,
-`Restore` will get your live site working again.
+@Restore@ will get your live site working again.
-Alas, **`Restore` is not designed to work across platforms**. Once you
-move your site to a new platform, `Restore` is powerless. It will
+Alas, *@Restore@ is not designed to work across platforms*. Once you
+move your site to a new platform, @Restore@ is powerless. It will
either fail completely, or else break things even worse, by reverting
-your *database*, but leaving the site on the new platform. All your
-old backups can no longer be used by the `Restore` task.
+your _database_, but leaving the site on the new platform. All your
+old backups can no longer be used by the @Restore@ task.
-You can still use these backups to [re-create the site
-manually](aegir-import)
+You can still use these backups to "re-create the site manually":aegir-import
from scratch, as you typically do when you import the site into Aegir.
-Always "Clone" to the Current Platform
---------------------------------------
+h2. Always "Clone" to the Current Platform
-Did you notice above how you should always `Clone` to the *current
-platform*, and then `Migrate`? This might seem like an extra step --
+Did you notice above how you should always @Clone@ to the *current
+platform*, and then @Migrate@? This might seem like an extra step --
why not just clone directly to the new platform?
Because it's all too easy to break your site. Permanently.
-You're asking Aegir to do too much at once. Both `Clone` and `Migrate`
+You're asking Aegir to do too much at once. Both @Clone@ and @Migrate@
require Aegir to check for all possible issues related to modules and
database updates.
-You need to test the `Clone` first, on the existing platform, and make
-sure there are no problems. If the clone works, you can `Migrate` to a
-new platform. Finally, run `Verify`.
+You need to test the @Clone@ first, on the existing platform, and make
+sure there are no problems. If the clone works, you can @Migrate@ to a
+new platform. Finally, run @Verify@.
-Always Create Platforms in "~/static"
---------------------------------------
+h2. Always Create Platforms in "~/static"
For security, you can only create custom platforms in one location:
-`~/static/`, in your home directory.
+@~/static/@, in your home directory.
-Don't try to create your platform in the `~/platforms/` directory.
-That's where the [default platforms](platforms-list) go.
+Don't try to create your platform in the @~/platforms/@ directory.
+That's where the "default platforms":platforms-list go.
These default platforms are actually installed in a separate directory
-tree, then symlinked into `~/platforms/` so that you can access them
+tree, then symlinked into @~/platforms/@ so that you can access them
with FTP or SSH. We do this to prevent access to the root level
directory in any default platform.
-Simply place your custom platforms in `~/static/`, each one with its
+Simply place your custom platforms in @~/static/@, each one with its
own subdirectory, and you'll have no problems.
-Always Install AdvAgg To the Right Directory
---------------------------------------------
-[AdvAgg](module-advagg) is a special module that aims to repair many of
+h2. Always Install AdvAgg To the Right Directory
+
+"AdvAgg":module-advagg is a special module that aims to repair many of
the caching difficulties with developing Drupal web sites. If you've
ever tried to tweak your CSS, refreshed, and gotten a broken layout,
AdvAgg may worth a look.
-However, because Aegir already has such granular [caching
-mechanisms](aegir-caching)
+However, because Aegir already has such granular "caching mechanisms":aegir-caching
in place, AdvAgg requires special treatment.
-Always install AdvAgg into **`sites/all/modules/advagg/`**.
+Always install AdvAgg into *@sites/all/modules/advagg/@*.
Other locations that might work for normal modules, *will not work
with AdvAgg*. Neither of these will work:
-- `sites/all/modules/contrib/advagg/`
-- `sites/foo.com/modules/advagg/`
+* @sites/all/modules/contrib/advagg/@
+* @sites/foo.com/modules/advagg/@
-### Enable All the AdvAgg Submodules You Need
+h3. Enable All the AdvAgg Submodules You Need
Also, enabling "AdvAgg" alone is not enough. You must enable at least
these four submodules:
-- Advanced CSS/JS Aggregation
-- AdvAgg Compress CSS
-- AdvAgg Compress Javascript
-- AdvAgg Bundler
+* Advanced CSS/JS Aggregation
+* AdvAgg Compress CSS
+* AdvAgg Compress Javascript
+* AdvAgg Bundler
The last submodule, “AdvAgg CDN Javascript”, is optional.
-### Remove AdvAgg Entirely
+h3. Remove AdvAgg Entirely
Even if you set up AdvAgg correctly, this module can sometimes make
your caching problems worse. If you decide to remove it, you will need
-to **completely remove AdvAgg** from that platform. Disabling and
+to *completely remove AdvAgg* from that platform. Disabling and
uninstalling the AdvAgg modules from your site is not enough. You must
-remove the entire subdirectory at `sites/all/modules/advagg/`.
+remove the entire subdirectory at @sites/all/modules/advagg/@.
-Always Put Contrib Modules in `sites/all/modules/`
---------------------------------------------------
+h2. Always Put Contrib Modules in @sites/all/modules/@
Drupal allows you to store contrib modules you download from
-[drupal.org](drupal) in several possible locations. But on Aegir,
+"drupal.org":drupal in several possible locations. But on Aegir,
there's only one good place to store your contrib modules:
-`sites/all/modules/`
+@sites/all/modules/@
All sites on the same platform should use the same set of modules.
-Each site doesn't have to *enable* all these modules. But no site
+Each site doesn't have to _enable_ all these modules. But no site
should have its own private copy of a contrib module.
Technically, you can give a site its own private copy of a module by
-placing it in the site's module directory (`sites/foo.com/modules/`).
-But these private copies will eventually cause **broken migrations**,
-as
-you try to `Migrate` your site to a new platform with upgraded
+placing it in the site's module directory (@sites/foo.com/modules/@).
+But these private copies will eventually cause *broken migrations*, as
+you try to @Migrate@ your site to a new platform with upgraded
modules. Let's see why.
-### You Forget Which Modules You've Stashed
+h3. You Forget Which Modules You've Stashed
First off, it's very easy to forget that, say, six months ago, you
stashed away some development copy of Views because you wanted a hot
new feature. When you've got five, ten, fifty sites on the same
-platform, you *really* don't want every upgrade to involve checking
-each individual site's `modules/` directory for nasty surprises.
+platform, you _really_ don't want every upgrade to involve checking
+each individual site's @modules/@ directory for nasty surprises.
-### Paths Change
+h3. Paths Change
-Also, what happens if you `Migrate` and change the domain for your
-site? If `foo.com` becomes `bar.com`, all the module paths in
-`sites/foo.com/modules/` change to `sites/bar.com/modules/`. They
+Also, what happens if you @Migrate@ and change the domain for your
+site? If @foo.com@ becomes @bar.com@, all the module paths in
+@sites/foo.com/modules/@ change to @sites/bar.com/modules/@. They
won't necessarily be available when Aegir needs them during the
upgrade.
-(If you think your paths might be broken, try to [repair the
-registry](registry-rebuild) with `drush rr`.)
+(If you think your paths might be broken, try to "repair the
+registry":registry-rebuild with @drush rr@.)
-### Aegir Only Compares `sites/all/modules/`
+h3. Aegir Only Compares @sites/all/modules/@
There's an even more serious reason to keep all your modules in
-`sites/all/modules/`. Those are the modules that **Aegir manages**.
-When
-you `Migrate` a site between platforms, Aegir compares
-`sites/all/modules/` on each platform, and does all kinds of magic for
+@sites/all/modules/@. Those are the modules that *Aegir manages*. When
+you @Migrate@ a site between platforms, Aegir compares
+@sites/all/modules/@ on each platform, and does all kinds of magic for
you.
For each module, Aegir checks version numbers, looks for needed
@@ -182,21 +173,21 @@ database upgrades, and gives you warnings and errors about potential
problems. This automatic module comparison is one of Aegir's most
amazing features.
-But this only happens for modules in `sites/all/modules/`. Aegir *does
-not* check each site's individual `modules/` directory. For Aegir,
-every `sites/foo.com/modules/` is a black box, and it simply copies
+But this only happens for modules in @sites/all/modules/@. Aegir *does
+not* check each site's individual @modules/@ directory. For Aegir,
+every @sites/foo.com/modules/@ is a black box, and it simply copies
that directory. No comparisons. Nothing.
What if your new platform has an upgraded module that conflicts with
-the version you stashed in `sites/foo.com/modules/`? Aegir _doesn't
-know_. It will *upgrade the database*, thinking the site needs to work
+the version you stashed in @sites/foo.com/modules/@? Aegir _doesn't
+know_. It will _upgrade the database_, thinking the site needs to work
for the module on the new platform. Then Drupal will still try to run
with the outdated copy.
That's a lot of mayhem waiting to happen. Play it safe. Keep your
-contrib modules in `sites/all/modules/`
+contrib modules in @sites/all/modules/@
-### What If I Need a Different Version of the Module?
+h3. What If I Need a Different Version of the Module?
Sometimes, a particular site does need that hot new feature in the
development version. Fortunately, this is exactly why they invented
@@ -204,31 +195,31 @@ platforms.
If your site needs a special version of a module, be generous (to your
future self) and make a new platform. That's what a platform is: a
-collection of modules *of particular versions* that all work together.
+collection of modules _of particular versions_ that all work together.
-Note that if you just want to *add* a new module, you don't have to
+Note that if you just want to _add_ a new module, you don't have to
make a whole new platform. As long as the new module won't cause havoc
with any existing modules on the platform (and this does happen), you
can enable the new module for one site while leaving it disabled for
all the rest.
-### Custom Modules Can Go in `sites/foo.com/modules/`
+h3. Custom Modules Can Go in @sites/foo.com/modules/@
-Is there any use for `sites/foo.com/modules`? Yes. This is where you
-put **custom, one-off modules you write yourself**. Since you'll be
+Is there any use for @sites/foo.com/modules@? Yes. This is where you
+put *custom, one-off modules you write yourself*. Since you'll be
managing these upgrades yourself anyway, you don't need Aegir to do
it.
(You'll still need to be careful about path changes, as mentioned
above.)
-### More on `sites/all/modules/`
+h3. More on @sites/all/modules/@
-Here's how `mig5`, an Aegir core developer, [explains
-this](http://community.aegirproject.org/node/243#comment-152)
+Here's how @mig5@, an Aegir core developer, "explains
+this":http://community.aegirproject.org/node/243#comment-152
bq.. Aegir doesn’t track site-specific modules/themes in
-`/sites/$yoursite/(modules|themes)` because it’s not possible to ever
+@/sites/$yoursite/(modules|themes)@ because it’s not possible to ever
upgrade those modules (they are tarballed up and moved with the site
on a Migration).
@@ -237,18 +228,17 @@ in this directory as you’ll never be able to upgrade them if you do
your upgrades properly (via Migrations, to new target platforms).
To have site-specific modules not in that directory, you should learn
-install profiles, and store the modules/themes in `/profiles
-/$yourprofile/(modules|themes)` for a site using that install
-profile....
+install profiles, and store the modules/themes in @/profiles
+/$yourprofile/(modules|themes)@ for a site using that install profile....
I don’t see us ever handling the upgrades of modules in
-`/sites/$site`, since that entire dir gets tarballed up and moved
+@/sites/$site@, since that entire dir gets tarballed up and moved
across. In fact we made a deliberate design decision to literally
ignore those modules in the Aegir package system.
-If you want to understand more, we recommend you [read the entire
-thread](http://community.aegirproject.org/node/243), as well as this
-[excellent handbook entry](http://community.aegirproject.org/node/23).
+p. If you want to understand more, we recommend you "read the entire
+thread":http://community.aegirproject.org/node/243, as well as this
+"excellent handbook entry":http://community.aegirproject.org/node/23.
[drupal]http://drupal.org
[good-habits]http://omega8.cc/are-there-any-specific-good-habits-to-learn-116
diff --git a/09.legacy/chapter.md b/09.legacy/chapter.md
index 4d37889..b9628b8 100644
--- a/09.legacy/chapter.md
+++ b/09.legacy/chapter.md
@@ -4,7 +4,7 @@ taxonomy:
category: docs
---
-### Work In Progress
+### Archive
# Legacy Docs
@@ -12,4 +12,4 @@ This area contains legacy docs imported as-is from our old Drupal site via WordP
They are full of incomplete Textile-to-Markdown and some HTML leftovers, which need to be fixed before they are re-used in proper docs written in Markdown on this site.
-Some of these legacy docs have been already rewritten in the meantime, but need to be updated, because the rewrite effort started in 2013, and things changed a bit in the meantime. Some still need to be rewritten, though, so we are including them here mainly as a source for the ongoing rewrite effort, now hopefully with **your** help!
+Some of these legacy docs have been already rewritten in the meantime, but need to be updated, because the rewrite effort started in 2013, and things changed _a bit_ in the meantime. Some still need to be rewritten, though, so we are publishing them here, mainly as a supporting source for the ongoing rewrite effort, continued now, hopefully, also with **your** help!