Ausgangssituation

Contao soll auf einem Server in einem eigenen Unterverzeichnis installiert werden. Dies kann aus verschiedenen Gründen erforderlich sein, beispielsweise:

1. um das Rootverzeichnis sauber und übersichtlich zu halten
2. weil mehrere Sites aus einem Rootverzeichnis zu hosten sind
3. weil parallel zu Contao auch andere Applikationen gespeichert werden sollen
4. weil neben den dynamischen Seiten von Contao auch statische Seiten gehostet werden
5. usw.

Das Ziel

Unter den unten beschriebenen Umgebungsbedingungen soll folgendes umgesetzt werden (alle Pfade sind nur Beispiele)

1. Durch Aufruf von "http://www.meinedomain.de/" oder bei lokaler Installation "http://localhost/" soll die index.php in "www/cms/" aufgerufen werden
2. Der Aufruf der Contao Seiten soll durch z.B. "http://www.meinedomain.de/index.html" oder "http://www.meinedomain.de/unterseiten/meine_unterseite.html" mit leicht lesbaren und suchmaschinenfreundlichen URLs erfolgen. Zu diesem Zweck ist auch FolderURL installiert.
3. Die Navigation innerhalb der mit Contao realisierten Webiste soll ohne den Pfadteil .../cms/.. erfolgen. Also NICHT: "http://www.meinedomain.de/cms/unterseite/meine_unterseite.html"
4. Wird eine statische Website im www-Rooverzeichnis z.B. "http://www.meinedomain.de/gibts_in_echt.html" aufgerufen, so soll diese auch angezeigt werden.
5. Wird eine andere Seite oder Anwendung in einem außerhalb von Contao real existierenden Unterverzeichnis aufgerufen z.B. "http://www.meinedomain.de/onlinegame/" soll auf dieses geroutet werden.

Die technischen Umgebungsbedingungen

Diese Anleitung bezieht sich auf die folgenden beispielhaften Umgebungsbedingungen:

1. Der Server (oder die lokale Installation) hat ein Wurzelverzeichnis, z.B. "www". Dieses wird nach Eingabe der domain "http://www.meinedomain.de/" oder bei lokaler Installation "http://localhost/" aufgerufen.
2. Contao ist in ein Unterverzeichnis dieses "www" Wurzelverzeichnisses kopiert, z.B: "cms". Der Pfad zu Contao lautet nun www/cms/. In diesem liegen nun die Ordner contao, plugins, system, templates, tl_files, typolight sowie u.a. die Datei .htaccess.default und die index.php
3. Die Erweiterung "FolderURL" ist in Contao installiert
4. Im Wurzelverzeichnis "www" befinden sich weitere Unterordner und/oder html/php files, die andere Anwendungen bzw. statische Webseiten beinhalten, die bei Bedarf erreichbar sein müssen.

Die Domainnamen, Pfade und Seiten sind natürlich nur Beispiele und müssen an die jeweilige Installation angepasst werden!

Die Umsetzung

Grundsätzlich gibt es mehrere Lösungsvarianten. Die hier beschriebene Variante erfolgt unter Nutzung der Apache .htaccess Dateien. Diese können entweder offline mit einem beliebigen Editor erstellt/bearbeitet und dann per FTP auf den Server hochgeladen werden oder per FTP-fähigem Editor direkt online editiert werden (z.B. mit Notepad++ http://notepad-plus-plus.org/ - gibt es auch als portable Version unter http://portableapps.com/ bzw. http://portableapps.com/de )

Schritt 1 - Installation im Unterverzeichnis

Contao wurde in ein Unterverzeichnis des Wurzelverzeichnisses am Server kopiert. Beispiel: Wurzelverzeichnis Server lautet "www" Installationsverzeichnis Contao lautet "cms". Der Pfad zu Contao lautet nun www/cms/. (siehe Pkt 2. technische Umgebungsbedingungen)

Schritt 2 - Anpassen der .htaccess im WURZELVERZEICHNIS

Als erstes ist die .htaccess im Wurzelverzeichnis anzupassen:

 RewriteEngine On
 RewriteBase /
 
 # in der folgenden Zeile den Text "cms"entsprechend dem gewählten Unterverzeichnis für Contao ggf. ändern
 RewriteCond %{REQUEST_URI} !^cms/.*
 
 # alternativ zur letzten Zeile oberhalb geht auch:
 # RewriteCond %{REQUEST_URI} !^(cms|verzeichnis1|verzeichnis2)/.*
 # wenn einige Verzeichnisse real existieren und NICHT von contao behandelt werden sollen!
 # mehrere Verzeichnisse sind einfach getrennt durch "|" nacheinander aufzulisten
 
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d [OR]
 RewriteCond %{REQUEST_URI} ^/$
 
 # in der folgenden Zeile ebenfalls den Text "cms" entsprechend dem gewählten Unterverzeichnis für Contao ändern
 RewriteRule ^(.*) /cms/$1 [L]
 
 # die folgende Zeile ist nur erforderlich, wenn ALLE Seitenaufrufe mit .html-Endung an Contao gehen sollen
 # RewriteRule .*\.html$ index.php [L]

Erklärung: Zuerst wird das Umschreiben von URLs aktiviert, wobei als Basis das aktuelle Verzeichnis festgesetzt wird (" RewriteEngine On " und " RewriteBase / ").

Anschließend werden URLs die direkt auf das Unterverzeichnis "cms" verweisen vom Umschreiben ausgenommen (" RewriteCond %{REQUEST_URI} !^cms/.* "). Das ist auch für mehrere Verzeichnisse möglich, wenn man Inhalte außerhalb von Contao auf der Website hat.

Sofern die in der URL aufgerufenen Verzeichnisse oder Files tatsächlich existieren, findet ebenfalls kein Umschreiben statt (" RewriteCond %{REQUEST_FILENAME} !-f " und " RewriteCond %{REQUEST_FILENAME} !-d [OR] ").

Alle anderen Aufrufe werden um das Unterverzeichnis ergänzt (" RewriteRule ^(.*) /cms/$1 [L] ").

So wird aus http://www.meinedomain.de/index.html die URL http://www.meinedomain.de/cms/index.html - was weder Nutzer noch Suchmaschine zu sehen bekommen!

Zu beachten ist, dass sich im Wurzelverzeichnis keine index.php oder index.html Datei befinden darf. (Achtung auf Reste voheriger Installationen ;-)

Schritt 3 - Anpassen der .htaccess im INSTALLATIONSVERZEICHNIS

Im Installationsverzeichnis von Contao kann nun praktisch unverändert die mitgelieferte .htaccess.default verwendet werden (natürlich muss die auf .htaccess umbenannt werden. Also das ".default" raus aus dem Dateinamen! Hier die Beispielversion:

##
# Contao Open Source CMS
# Copyright (C) 2005-2011 Leo Feyer
#
# Formerly known as TYPOlight Open Source CMS.
#
# This program is free software: you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation, either
# version 3 of the License, or (at your option) any later version.
# 
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
# 
# You should have received a copy of the GNU Lesser General Public
# License along with this program. If not, please visit the Free
# Software Foundation website at <http://www.gnu.org/licenses/>.
#
# PHP version 5
# @copyright  Leo Feyer 2005-2011
# @author     Leo Feyer <http://www.contao.org>
# @license    LGPL
##
 
##
# Disable ETags
# @see http://developer.yahoo.com/performance/rules.html#etags
##
FileETag None
 
##
# Prevent access to the Contao template files
##
<FilesMatch "\.(tpl|html5|xhtml)$">
  Order allow,deny
  Deny from all
</FilesMatch>
 
<IfModule mod_mime.c>
 
  ##
  # Serve the correct content type for .htc files (CSS3 PIE)
  # @see http://css3pie.com/documentation/known-issues/#content-type
  ##
  AddType text/x-component .htc
 
</IfModule>
 
<IfModule mod_deflate.c>
 
  ##
  # Use mod_deflate to compress JavaScript, CSS, XML, HTML and PHP files.
  # @see http://developer.yahoo.com/performance/rules.html#gzip
  ##
  <FilesMatch "\.(css|js|xml|html?|php)$">
    SetOutputFilter DEFLATE
  </FilesMatch>
 
</IfModule>
 
<IfModule mod_headers.c>
 
  ##
  # Disable ETags
  # @see http://developer.yahoo.com/performance/rules.html#etags
  ##
  Header unset ETag
 
  ##
  # Add a Vary Accept-Encoding header for the compressed resources. If you
  # modify the file types above, make sure to change them here accordingly.
  # @see http://developer.yahoo.com/performance/rules.html#gzip
  ##
  <FilesMatch "\.(js|css|xml|gz)$">
    Header append Vary Accept-Encoding
  </FilesMatch>
 
</IfModule>
 
<IfModule mod_expires.c>
 
  ##
  # Activate the module
  ##
  ExpiresActive On
 
  ##
  # Specify an expiration 30 days in the future for images, JavaScripts and
  # CSS files. Edit or remove the lines to set up your own expiration logic.
  # @see http://developer.yahoo.com/performance/rules.html#expires
  ##
  ExpiresByType image/png A2592000
  ExpiresByType image/gif A2592000
  ExpiresByType image/jpg A2592000
  ExpiresByType image/jpeg A2592000
  ExpiresByType text/javascript A2592000
  ExpiresByType application/x-javascript A2592000
  ExpiresByType application/javascript A2592000
  ExpiresByType text/css A2592000
  ExpiresByType image/x-icon A2592000
 
</IfModule>
 
<IfModule mod_rewrite.c>
 
  ##
  # Activate the module
  ##
  RewriteEngine On
 
  ##
  # Set the RewriteBase if your Contao installation is in a subdirectoy and
  # the rewrite rules are not working properly. Usage examples:
  #
  #   RewriteBase /contao-2.9.0
  #   RewriteBase /path/to/contao
  #
  # Uncomment the following line to set the RewriteBase.
  ##
  RewriteBase /
 
  ##
  # Contao usually does not pass absolute URLs via GET, therefore the
  # following rules block all requests that try to pass a URL or the /etc/
  # directory as parameter (malicious requests).
  ##
  RewriteCond %{REQUEST_URI} (ftp|https?):|/etc/ [NC,OR]
  RewriteCond %{QUERY_STRING} (ftp|https?):|/etc/ [NC]
  RewriteRule .* - [F,L]
 
  ##
  # Uncomment the following lines and replace "domain.com" with your domain
  # name to redirect requests without "www" to the correct domain. 
  ##
  #RewriteCond %{HTTP_HOST} ^domain\.com [NC]
  #RewriteRule (.*) http://www.domain.com/$1 [R=301,L]
 
  ##
  # If you cannot use mod_deflate, uncomment the following lines to load a
  # compressed .gz version of the bigger Contao JavaScript and CSS files.
  ##
  #AddEncoding gzip .gz
  #<FilesMatch "\.js\.gz$">
  #  AddType "text/javascript" .gz
  #</FilesMatch>
  #<FilesMatch "\.css\.gz$">
  #  AddType "text/css" .gz
  #</FilesMatch>
  #RewriteCond %{HTTP:Accept-encoding} gzip
  #RewriteCond %{REQUEST_FILENAME} \.(js|css)$
  #RewriteCond %{REQUEST_FILENAME}.gz -f
  #RewriteRule ^(.*)$ $1.gz [QSA,L]
 
  ##
  # Do not rewrite requests for static files or folders such as style sheets,
  # images, movies or text documents.
  ##
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
 
  ##
  # By default, Contao adds ".html" to the generated URLs to simulate static
  # HTML documents. If you change the URL suffix in the back end settings, make
  # sure to change it here accordingly!
  #
  #   RewriteRule .*\.html$ index.php [L]   # URL suffix .html
  #   RewriteRule .* index.php [L]          # No URL suffix
  #   RewriteRule .*\.txt$ index.php [L]    # URL suffix .txt
  #
  # If you are using mod_cache, it is recommended to use the RewriteRule below,
  # which adds the query string to the internal URL:
  # 
  #   RewriteRule (.*\.html)$ index.php/$1 [L]
  #
  # Note that not all environments support mod_rewrite and mod_cache.
  ##
  # RewriteRule .*\.html$ index.php [L]
  # Rewrite TYPOlight URLs
 
  # mit den folgenden zwei Zeilen sollte es immer klappen, notwendig ist im Prinzip
  # nur jeweils eine davon, siehe Erklärung weiter oben
  RewriteRule .*$ index.php [L]
  RewriteRule (.*\.html)$ index.php/$1 [L]
 
</IfModule>

Zu beachten ist: - die RewriteBase der .htaccess im Installationsverzeichnis darf KEIN Unterverzeichnis beinhalten, sondern lautet: "RewriteBase /" . Die Umleitung auf den Unterordner "cms" wurde ja schon von der .htaccess im Wurzelverzeichnis übernommen! - die RewriteRule am Ende der .htaccess ist auf zwei Regeln gestellt

1. "RewriteRule .*$ index.php [L]" - dadurch werden auch Dateinamen gültig aufgerufen, wenn der User das abschließende .html vergisst oder den Dateinamen irrtümlich als Pfad eingibt,
2. " RewriteRule (.*\.html)$ index.php/$1 [L]" - falls mod_cache verwendet wird, sonst kann es zu merkwürdigem Verhalten kommen.

(Anm.: eine Umschreibung, dass bei Eingabe der Endung .htm (statt .html) auch richtig umgeschrieben wird, wird noch gesucht)

Schritt 4 - Anpassen im Contao Backend

Im Contao Backend ist der Installationspfad unter Einstellungen > Globale Einstellungen > Relativer Pfad zum Contao-Verzeichnis LEER zu lassen (weil diese Aufgabe von der .htaccess im Wurzelverzeichnis übernommen wird).

Alternativ kann man das auch in der localconfig.php im Unterverzeichnis system von Contao manuell einstellen. Pfad/Datei gemäß Beispiel also: www/cms/system/localconfig.php Wobei die Zeile zur Einstellung des Websitepfades leer sein muss

$GLOBALS['TL_CONFIG']['websitePath'] = '';

Eine manuelle Änderung kann nach einem Update oder dem Verschieben der Installation erforderlich sein, wenn sich das Contao-BE nicht aufrufen lässt. Zudem stellt Contao bei Neuinstallation den Pfad automatisch auf das Unterverzeichnis ein, was in diesem Fall aber nicht erforderlich ist, sondern zu einem Fehler führt.

Ab Version 3.x erstellt Contao bei der Installation anstelle des Eintrags in der localconfig.php eine separate Datei pathconfig.php (ebenfalls im system-Verzeichnis). Diese muss gelöscht werden - auch nach einem Update. Eine Änderung über das Backend ist nicht möglich.

Schritt 5 - Anpassen von Verzeichnissen außerhalb Contao

Sollen Dokumente in Verzeichnissen außerhalb von Contao ohne Einschränkungen aufgerufen werden können, so muss man im jeweiligen Unterverzeichnis (unterhalb des Wurzelverzeichnisses) eine eigene .htaccess Datei anlegen. Diese muss nur die Zeile

 RewriteEngine Off

beinhalten. Dadurch kann auf alle *.htm, *.html und *.php-Seiten in diesem Unterverzeichnis zugegriffen werden. Alternativ kann diese .htaccess auch eigene Regeln beinhalten.

Sofern diese Verzeichnisse aber in der .htaccess im Wurzelverzeichnis wie beschrieben angegeben worden sind, ist dies nicht zwingend erforderlich.

Ergebnis: Aufruf der Seiten

Aufruf Frontend-Seiten

Folgendes sollte nun funktionieren (an Hand der Beispielvorgaben):

Anmerkungen Die Datei "gibt_es.html" (bzw. *.htm oder *.php) bezeichnet eine physikalisch(?) existente Datei.
Der Folder "ausserhalb_von_contao" bezeichnet einen physikalisch(?) existenten Ordner, der sich NICHT im Contao Installationsverzeichnis befindet und auch nicht durch Contao bzw. FolderURL erzeugt wird.
Die Datei "sonst_eine_cmsseite" bezeichnet eine Seite, die durch Contao bereitgestellt wird.
Der Folder "cmsunterordner" bezeichnet einen "virtuellen" Ordner, der durch Contao bzw. FolderURL erzeugt wird.

Aufrufe an Contao

• Aufruf per "http://www.meinedomain.de/index.html" => geht ok an contao
• Aufruf per "http://www.meinedomain.de/sonst_eine_cmsseite.html" => geht ok an contao
• Aufruf per "http://www.meinedomain.de/sonst_eine_cmsseite" => geht ok an contao wie "http://meinedomain.de/sonst_eine_seite.html
• Aufruf per "http://www.meinedomain.de/sonst_eine_cmsseite/" => geht ok an contao wie "http://meinedomain.de/sonst_eine_seite.html
• Aufruf per "http://www.meinedomain.de/cmsunterordner/sonst_eine_cmsseite.html" => geht ok an contao
• Contao verlinkt die Seiten beim Rendern richtig ohne das .../cms/.. (Installationsverzeichnis) dazwischen

Aufrufe außerhalb von Contao

• Aufruf von "http://www.meinedomain.de/gibt_es.htm" funktioniert, ruft die real bestehende *.htm Seite im Wurzelverzeichnis auf
• Aufruf von "http://www.meinedomain.de/gibt_es.html" funktioniert, ruft die real bestehende *.html Seite im Wurzelverzeichnis auf
• Aufruf von "http://www.meinedomain.de/ausserhalb_von_contao/gibt_es.php" funktioniert, ruft die real bestehende *.php Seite im Wurzelverzeichnis auf
• Aufruf von "http://www.meinedomain.de/ausserhalb_von_contao/" funktioniert und öffnet die default html od. php-Seite (index.html, index.htm, index.php) in diesem Unterordner (parallel zu Contao)
• Aufruf von "http://www.meinedomain.de/ausserhalb_von_contao/gibt_es.htm" oder "http://meinedomain.de/ausserhalb_von_contao/gibt_es.html" oder "http://meinedomain.de/ausserhalb_von_contao/gibt_es.php" funktionieren und öffnen die jeweiligen Seiten
• für von anderen Applikationen bereitgestellten Seiten in eigenen Unterverzeichnissen unter dem Wurzelverzeichnis und parallell zu Contao sind im jeweiligen Verzeichnis zumeist eigene .htaccess Dateien erforderlich

Sofern die aufgerufenen Seiten ausserhalb von Contao nicht bestehen, bzw. keine eigene Applikation dahintersteht

• erscheint die in Contao für nichtexistente Seiten eingestellte Fehlermeldung/-seite (404)
• ausgenommen die .htaccess im Ordner der aufgerufenen Seite bestimmt ein anderes Verhalten (z.B. mit RewriteEngine Off)

Aufruf Backend-Seiten

Das Contao Backend kann nun entweder über

http://www.meinedomain.de/contao/ 

oder über

http://www.meinedomain.de/cms/contao

erfolgen.

Cave: Wenn man schon mal im Backend angemeldet war, dann kann es sein, das man immer einen Umleitungsfehler bekommt. Einmal die Cookies von dieser Domain löschen und das Problem ist beseitigt.