H-Quadrat IT TechBlog » multi-domain

MODx Revolution multi-Domain Context Installation english

Henning T. Heil — Mon, 30 Nov 2009 02:27:00 +0000

With the introduction of the new “Revolution” release of the MODX Content Management System the developer team has implemented native support for serving multiple domains with one installation of the MODx software. Up to date such a constellation was only possible with workarounds and those so called solutions were not always 100% bullet proof under all aspects of web development.
In the following I have written a multiple domain tutorial for MODx Revolution and going with that I say thank you to Jason Coward (opengeek) who has supported my first multi-domain install and numberless other MODx topics with a lot of his “good open soucre energy”.

Diese Anleitung gibt es auch auf Deutsch.

Presumptions

This tutorial is based on the assumption that all domains that shall be served by this MODx Revolution installation are pointing to one and the same directory/the same document root on your web server, e.g. /var/www/localhost/htdocs or /var/www/localhost/modxrevomulti or a corresponding path on other operating systems.
This tutorial uses the domains modx-templates.com, ffmwireless.de, thesearchgoeson.com for demonstration, their usage might change in the future.
Versions: the first succesful multi-domain test I installed with Revolution beta-2, for this tutorial a beta-5 SVN is used. With future versions of MODx Revolution the version number should not play a role any more.
Furthermore I exclude the discussion of author rights between multiple contexts because I don’t need them :-) – for your project you might want to check this before you start.
This tutorial presumes you have a plain MODx Revolution installation ready and haven’t made any bigger changes or none at all. If not: here you can find the necessary MODx installation files.
I have changed the System > System Settings to activate the friendly_urls and corresponding settings but don’t assume this is mandatory for a multi-domain installation.

Contexts

The complete architectural redesign of MODx Revolution introduces under the keyword “contexts” the concept of encapsulating the elements of each website (or other elements) into a separate area in the MODx internal data structure – into a context.

After the basic installation of a MODx Revolution package the Manager looks as follows (I have added some example documents):

Picture 1: MODx Revolution default installation

You see the default Context web which is always installed with MODx and the 3 documents “Start”, “MODx Revo … Tutorial” and “Error 404 page”.

If you now navigate to the overview of Contexts in MODx (Menu System > Contexts),

Picture 2: MODx Contexts view and "Create Context" dialog

you can find 2 entries: web, the already mentioned default-Context for the first website and mgr, the MODx Manager that plays a special role and holds the MODx administrational backend.

To these Contexts we now add two more, one for each domain we want to serve additionally in the future. After the creation of the two additional Contexts the MODx-Manager looks like this

Picture 3: MODx Contexts for additional domains have been added

Now we furthermore add some standard documents to the Contexts, you need at least one start page/index page per domain/context and also one error page for each.
Names and descriptions are not important, we will only need the document IDs for the later completion of the Contexts configuration. After adding the documents for each of your domains the document structure should look similar to this

Picture 4: MODx-Manager after adding the default documents for each context/domain

Completion of the additional Contexts configuration in MODx Manager

Contexts can be configured completely independent but in the first place they inherit all known website-settings from the base installation and hence we will (have to) change some of the Contexts’ parameters.

Open the Contexts view again via System > Contexts and what you will likely see is the view of Picture 3 above.
Right-click the Context you want to edit (I start with “thesearch”) and choose “Update Context” from the upcoming menu. The Context is now opened in the editing mode and you will have to switch to the “Context Settings” tab, then you will see the following

Bild 5: MODx Context editing mode

You now add, one after the other, the following configuration keys by clicking on Create new

key  |  value

http_host  |  www.thesearchgoeson.com
site_url  |  http://www.thesearchgoeson.com
base_url  |  /
site_name  |  MODxCMS TheSearchGoesOn test
site_start  |  6
error_page  |  7  [optional, aber empfehlenswert]
default_template  |  3  [optional, wenn Sie mehrere templates vorbereitet haben]

Besides key & value you also have to fill out the field name in the dialog, there you can fill in whatever seems fitting and the other fields can stay as predefined or – where you like it – can be filled with additional descriptions. The values for site_start and error_page you can see in picture 4 or according to the settings on your web page.

When MODx finds an already existing value for the field name in the shipped language files, your manually added name might now be shown (and this behaviour might change in the future). After all settings/keys are done the Context parameters look as follows (sorted by key)

MODx Context configured completely

Repeat the last step for all domains/contexts you want to use, I have meanwhile also configured keys for the Context ffmwireless - and so we can proceed to the last step of this tutorial.

Mapping of domains and contexts in the index.php file

In the end follows a last simple step in the index.php file in your MODx root-directory (= thedocumentroot fo your webserver for this MODx installation), you can see the file contents here as originally shipped with MODx Revolution.

Delete or comment line 89

//$modx->initialize('web');

by adding the two slashes “//” in front and add the following code-block directly below the line, of course changed for your domain names and the number of domains you want to run with this MODx Revolution installation

/* setup for multiple domains */
switch(strtolower(MODX_HTTP_HOST)) {
   case 'www.modx-templates.com:80':
   case 'www.modx-templates.com':
      // if the http_host is modx-templates.com, switch the context to web
      $modx->initialize('web');
      break;
   case 'www.ffmwireless.de:80':
   case 'www.ffmwireless.de':
      // if the http_host is ffmwireless.de, switch the context to ffmwireless
      $modx->initialize('ffmwireless');
      break;
   case 'www.thesearchgoeson.com:80':
   case 'www.thesearchgoeson.com':
      // if the http_host is thesearchgoeson.com, switch the context to thesearch
      $modx->initialize('thesearch');
      break;
  default:
      // by default / if no other rule can be applied, load 'web' context
      $modx->initialize('web');
      break;
}

After your code-block should only be the follwing lines from the original code

/* execute the request handler */
if (!MODX_API_MODE) {
    $modx->handleRequest();
}

the complete new MODx indx.php file you can finde here (lines 91 – 112 have been changed).

That’s it, you made it – MODx is running with multiple domains and you can apply the tutorial for even more domains/contexts or other constellations!

MODx Revolution multi-Domain Context Installation

Henning T. Heil — Mon, 30 Nov 2009 00:15:11 +0000

Mit Einführung der neuen “Revolution”-Generation des MODX Content Management Systems ist es möglich, mehrere Domains mit einer Installation der Software MODx zu betreiben. Bisher war eine solche Konstellation nur mit workarounds zu erreichen und diese Lösungen waren auch nicht immer unter allen Aspekten der Web-Kunst 100% zuverlässig.
Nachfolgend also eine Anleitung für MODx Revolution und damit verbunden herzlichen Dank an Jason Coward (opengeek), der bei der Erstinstallation und zahllosen anderen MODx-Themen mit viel OpenSource-Energie unterstützt hat.

This document is also available in english.

Annahmen

Diese Anleitung basiert darauf, dass alle von der MODx Revolution Installation zu bedienenden Domains auf ein und das selbe Verzeichnis/den gleichen documentroot auf Ihrem webserver zeigen, z.B. /var/www/localhost/htdocs oder /var/www/localhost/modxrevomulti oder einem entsprechenden Pfad auf anderen Betriebssystemen.
In diesem Tutorial werden die Domains modx-templates.com, ffmwireless.de, thesearchgoeson.com testweise genutzt, deren Verwendung könnte sich zukünftig wieder einmal ändern.
Versionen: Den ersten erfolgreichen multi-Domain-Test hatte ich in Revolution beta-2 durchgeführt, für dieses Tutorial wird eine beta-5 SVN verwendet, die Version sollte aber zukünftig keine Rolle mehr spielen.
Weiterhin klammere ich die Betrachtung der Autorenrechte und deren Abgrenzung zwischen den Domains im MODx-Manager aus, weil ich sie nicht benötige :-) – für Ihr Projekt sollten Sie dies gegebenenfalls vorher prüfen.
Diese Einführung geht davon aus, dass Sie bereits eine MODx Revolution Installation in Betrieb genommen und keine grösseren Änderungen daran vorgenommen haben. Falls nicht: hier gibt es die benötigten MODx-Installationsdateien.
Ich habe in den System > System Settings die friendly_urls und zugehörige Einstellungen eingeschaltet, das ist jedoch nicht zwingend.

Contexts

Der komplette architekturelle Neuaufbau führt im MODx “Revolution”-release unter dem Stichwort “Contexts” das Konzept ein, jeder website – und anderen Elementen – innnerhalb der MODx-Datenstrukturen einen eigenen, gekapselten Bereich zuzuordnen – eben einen Kontext.

Nach der normalen Installation eines MODx Revolution Paketes sieht der Manager etwa wie folgt aus, einige Beispieldokumente habe ich bereits hinzugefügt:

Bild 1: MODx Revolution Basisinstallation

Sie sehen den Standard-Context web, den MODx immer installiert und die 3 Dokumente “Start”, “MODx Revo … Tutorial” und “Error 404 page”.

Betrachtet man sich nun die Übersicht der Contexts in MODx (Menu System > Contexts),

Bild2: MODx Contexts Ansicht und "Create Context" Dialog

so sieht man 2 Einträge: web, den bereits angesprochenen Standard-Context für die 1. website und mgr, den MODx Manager, der eine Sonderrolle einnimmt und das MODx-Verwaltungs-backend enthält.

Diesen Contexts fügen wir nun zwei weitere hinzu, für jede zusätzlich zu behandelnde Domain einen. Nach der Erstellung der zusätzlichen Contexts sieht es im MODx-Manager dann folgendermassen aus

Bild 3: MODx Contexts für zusätzliche Domains hinzugefügt

Fügen Sie nun den Contexts noch einige zukünftige Standarddokumente hinzu, Sie benötigen mindestens eine Startseite/Indexseite pro Domain/Context und jeweils eine Fehlerseite.
Dabei sind Namen und Bezeichnungen nebensächlich, lediglich die Dokument-IDs benötigen wir später für die Komplettierung der Konfiguration der Contexts. Danach sollte es für jede Ihrer Domains in etwa so aussehen

Bild 4: MODx-Manager nach der Einrichtung der Standarddokumente für jeden Context/Domain

Weitere Einrichtung der zusätzlichen Contexts im MODx Manager

Contexts sind komplett unabhängig konfigurierbar, erben aber zunächst nach dem inheritance-Prinzip alle von der Basisinstallation bekannten website-Parameter und wir werden folglich einige Parameter der jeweiligen Contexts anpassen (müssen).

Öffnen Sie im Manager zunächst wieder über System > Contexts die Ansicht der Contexts, Sie sehen dann wieder eine Ansicht entsprechend Bild 3.
Klicken Sie mit der rechten Maustaste auf den zu bearbeitenden Context (ich beginne mit “thesearch”) und wählen Sie im erscheinenden Menu “Update Context” aus. Darauf hin erscheint der Context in der Bearbeitungsansicht und Sie müssen noch auf den Reiter “Context Settings” wechseln, die dann folgende Ansicht sehen Sie hier

Bild 5: MODx Context Bearbeiten Ansicht

Sie ergänzen nun nacheinander folgende Angaben durch einen Klick auf Create new

key  |  value

http_host  |  www.thesearchgoeson.com
site_url  |  http://www.thesearchgoeson.com
base_url  |  /
site_name  |  MODxCMS TheSearchGoesOn test
site_start  |  6
error_page  |  7  [optional, aber empfehlenswert]
default_template  |  3  [optional, wenn Sie mehrere templates vorbereitet haben]

Neben key & value müssen Sie im Dialog auch das Feld name befüllen, hier setzen Sie zweckmässige Bezeichnungen ein und die anderen Felder können Sie entsprechend der Voreinstellungen im Dialog belassen oder wo angebracht mit weiteren Informationen versehen. Die Werte für site_start und error_page können Sie in Bild 4 oder entsprechend der Angaben auf Ihrer Seite ablesen.

Wenn MODx für den eingegebenen key bereits einen Wert für das Feld name in der mitgelieferten Sprachdatei findet, werden Ihre manuellen Angaben ggf. nicht angezeigt. Am Ende der Einstellungen sehen die Context-Parameter dann etwa wie folgt aus (sortiert nach key)

MODx Context konfiguriert

Wiederholen Sie diesen Schritt für die weiteren von Ihnen einzurichtenden Domains, ich habe den Context ffmwireless ebenfalls mit den entsprechenden Einstellungen versehen und wir können damit zum letzten Schritt des Tutorials übergehen.

Mapping der Domains und Contexts in der Datei index.php

Zuletzt noch ein einfacher Schritt in der index.php in Ihrem MODx Wurzelverzeichnis (= dem documentroot Ihres webservers für diese MODx-Installation), Sie können diese Datei hier im Originalzustand sehen.

Löschen oder kommentieren Sie nun die Zeile 89

//$modx->initialize('web');

in dem Sie die beiden slashes “//” voranstellen und ergänzen Sie direkt nach dieser Zeile den folgenden code-Block, natürlich angepasst an Ihre Domainnamen und die Anzahl der von Ihrer Installation zu betreibenden Domains

/* setup for multiple domains */
switch(strtolower(MODX_HTTP_HOST)) {
   case 'www.modx-templates.com:80':
   case 'www.modx-templates.com':
      // if the http_host is modx-templates.com, switch the context to web
      $modx->initialize('web');
      break;
   case 'www.ffmwireless.de:80':
   case 'www.ffmwireless.de':
      // if the http_host is ffmwireless.de, switch the context to ffmwireless
      $modx->initialize('ffmwireless');
      break;
   case 'www.thesearchgoeson.com:80':
   case 'www.thesearchgoeson.com':
      // if the http_host is thesearchgoeson.com, switch the context to thesearch
      $modx->initialize('thesearch');
      break;
  default:
      // by default / if no other rule can be applied, load 'web' context
      $modx->initialize('web');
      break;
}

Nach Ihrem code-Block sollten nun noch diese Zeilen

/* execute the request handler */
if (!MODX_API_MODE) {
    $modx->handleRequest();
}

aus dem Originalcode stehen, die gesamte neue MODx indx.php Datei können Sie hier betrachten (Zeilen 91 – 112 wurden verändert).

Das war’s, Sie haben es geschafft – MODx läuft mit mehreren Domains und Sie können diese Vorgehensweise auch bei weiteren Domains/Contexts oder anderen Anlässen anwenden!