Website Developer HowTo

Überblick

Alle Webseiten der mdlug website werden via CVS verwaltet. Das Prozedere zum Aktualisieren der Website sieht wie folgt aus:

  1. DocumentRoot Verzeichnis via CVS auschecken
  2. Dateien hinzufügen/aktualisieren/löschen
  3. Navigations-Menüs aktualisieren (optional)
  4. Änderungen ins CVS-Repository übernehmen
  5. Downloads bereitstellen (falls notwendig)
  6. Website aktualisieren

Es ist zu beachten, daß Binär-Dateien (z.B. PDF-, StarOffice-Dateien oder Programme), die hauptsächlich zum Download bereitgestellt werden sollen, NICHT im CVS sondern in einem separaten Verzeichnis auf dem Webserver bereitzustellen sind, um den Ressourcen-Bedarf bzgl. Backup, CVS und Bandbreite zu minimieren.

Im folgenden sind die jeweiligen Aktionen und die zugehörigen Informationen im Detail beschrieben.

DocumentRoot-Ordners via CVS auschecken

Jedes Mitglied des Mdlug-Webteams hat einen eigenen Account auf dem entsprechenden CVS- sowie Web-Server. Dieser ist notwendig, da das CVS-Repository nicht öffentlich sondern nur lokal zugänglich ist. Der Zugriff auf den jeweiligen Server ist nur mittels Secure Shell bzw. Open SSH Client erlaubt/möglich.

Die entsprechenden CVS-Parameter sind:

Host cvs.mdlug.de
Port default
Pfad /home/cvs/web
Modul mdlug.htdocs

An der Kommandozeile könnte ein checkout also z.B. so aussehen:

user.athome /tmp > export CVSROOT=:ext:account@cvs.mdlug.de:/home/cvs/web
user.athome /tmp > export CVS_RSH=ssh2
user.athome /tmp > cvs co mdlug.htdocs		
user.athome /tmp > cd mdlug.htdocs		
user.athome /tmp/mdlug.htdocs > 
Tipp

Je nach Einstellung versucht die ssh oftmals auch ein X-Forwarding aufzusetzen, was zu unnötigen Wartezeiten/Timeouts führt. Um dies zu vermeiden, kann man folgendes Script verwenden und die CVS_RSH Variable auf das entsprechende Script setzen: 

#!/bin/sh
exec ssh -x "$@"

Dateien hinzufügen/aktualisieren/löschen

Dateien können auf die übliche Art via cvs mit dem add bzw. delete hinzugefügt bzw. gelöscht werden (siehe auch CVS Parameter). Zu beachten ist, daß vor einem cvs delete datei die jeweilige Datei lokal gelöscht worden sein muß. Anderenfalls ignoriert cvs den Befehl mit einer entsprechenden Fehlermeldung. Beispiel: 

user.athome /tmp/mdlug.htdocs > cd events/themenabend/
user.athome /tmp/mdlug.htdocs/events/themenabend > cp ../../includes/template.html gnome.shtml
user.athome /tmp/mdlug.htdocs/events/themenabend > cvs add gnome.shtml
user.athome /tmp/mdlug.htdocs/events/themenabend > rm old.shtml
user.athome /tmp/mdlug.htdocs/events/themenabend > cvs delete old.shtml

Dateien können mit jedem für den jeweiligen Dateityp geeigneten Editor geändert werden. Generell werden hier emacs als auch eclipse + oxygen >= 3.0m5 empfohlen, da diese für [s]html und andere XML basierte Dateien ein geeignetes Highlighting, tag insights und eine Verifikation der Dateien unterstützen.

Regeln

  1. Für eine kooperative, effiziente Arbeit ist die Einhaltung "unserer" Standards und Konventionen für Quelltexte zwingend notwendig.

  2. Unterhalb des DocumentRoot-Ordners werden nur Dateien abgelegt, die zur Darstellung der jeweiligen Webseiten notwendig sind.

  3. Alle anderen [Binär-]Dateien, die zum Download vorgesehen sind, werden im separaten Download-Verzeichnis für die Website abgelegt, welches grundsätzlich über das Prefix /download/ zu referenzieren ist (siehe auch Downloads bereitstellen).

  4. Die Datei-Namen menu.xml und menu.html sind für die Erzeugung von Webseiten-Navigations-Elementen reserviert und sind nur für diesen Zweck einzusetzen (siehe Navigations-Menüs aktualisieren).

  5. Alle Ordner sind thematisch in einer Hierarchie aka Baum angeordnet. Es ist darauf zu achten, daß die max. Pfad-Länge aka Tiefe von 4 möglichst nicht überschritten wird (um Nutzern Tipp- bzw. Klick-Orgien zu ersparen).

  6. Jeder Ordner repräsentiert maximal einen Menu-Punkt im Navigations-Menu.

  7. Namen für Ordner als auch HTML-Dokumente bestehen grundsätzlich aus Kleinbuchstaben, sollten möglichst kurz gehalten werden und keine Umlaute oder Sonderzeichen enthalten.

  8. Links (egal ob symbolisch oder hart) sind nicht erlaubt, auch wenn das Dateisystem selbige unterstützt!

  9. Als Grundgerüst aka Vorlage für jede HTML-Datei ist die Datei /includes/template.html zu verwenden und die neue Datei mit der Endung .shtml zu versehen, um Server Side Includes nutzen als auch ein einheitliches Layout wahren zu können.

  10. Stile bzgl. Darstellung verschiendener Elemente sind, falls von globaler Bedeutung, in den betreffenden Dateien unter /styles/ festzuhalten.

  11. Der Einsatz von CGI-Scripts ist auf ein Mindestmaß zu reduzieren (siehe auch Welche Sprache für CGIs/Scripting ?).

  12. Alle nicht-öffentlichen Dokumente bzw. Scripte sind unterhalb des Mitgliederbereichs, d.h. im Ordner /intern/ bzw. /download/intern/ bzw. /cgi-bin/intern/abzulegen.

  13. Die Verwendung von Frames sollte in allen Webseiten vermieden werden. Nur wenn es wirklich notwendig und sinnvoll ist (sehr selten), können Frames in Betracht gezogen werden. Problem bei Frames sind einerseits Suchmaschinen (verzweigen nicht in die vom Frame-Dokument referenzierten Seiten) und andererseits starke Probleme beim Handling der Frames/Sessions bzw. Navigation (jeder hat beispielsweise sicher schon mal das Verschachteln einer Seite in sich selbst gesehen ...).

  14. Folgende ids sind reserviert und sollten nur in /includes Dateien verwendet werden, da eine id nur ein einziges mal innerhalb eines Dokuments zur Markierung eines Elements verwendet werden darf (XML Standard):

    • head
    • menu
    • content
    • footer

  15. Wurde eine Datei hinzugefügt oder geändert, so ist sie bzgl. Einhaltung des XHTML-Standards zu validieren. Da SSI-Befehle als Kommentare formuliert werden, muß das Dokument auch lokal, d.h. wenn es nicht vom Apache-Server geholt wird, gültig sein.

    Ein Möglichkeit zur Validierung ist die Benutzung von xmllint oder oxygen.

    xmllint --noout --valid info.shtml

    xmllint ist Bestandteil der XML C Bibliothek für GNOME und sollte auf jedem System vorhanden sein, auf dem GNOME 2.x läuft. Erkennt xmllint einen Fehler, so wird dieser ausgegeben, anderenfalls wird nichts ausgegeben.

    Tipp

    Um zu vermeiden, daß man mit dem Internet verbunden sein muß, um die Dateien verifizieren zu können (holen der DTDs) bzw. die Validierung etwas schneller vorangeht, kann man XML Kataloge aufsetzen, welche die jeweiligen Public Identifier (z.B. "-//W3C//DTD XHTML 1.1//EN") bzw. System Identifier (z.B. "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd") auf eine lokale Datei mapped, welche widerum die entsprechende DTD enthält.

    Wer noch keinen solchen Katalog besitzt, kann sich das Paket w3dtds.tgz herunterladen. Informationen bzgl. Software-Vorausetzungen als auch dem Setup findet ihr in der Datei w3dtds.README

Änderungen an kopierten Vorlagen

Grundsätzlich sollte die Vorlage /includes/template.html zur Erstellung von neuen Webseiten genutzt werden (siehe Regeln). Wurde die Vorlage auf eine neue Datei kopiert, sind die markierten Teile entsprechend anzupassen (alles andere sollte so bleiben, wie es ist): 

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE  html PUBLIC "-//W3C//DTD XHTML 1.1//EN" 
	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<!-- $Id: howto.shtml,v 1.7 2004/01/30 04:45:56 elkner Exp $ -->
<head>
<title>Vorlage: mdlug e.V.</title>
<meta name="description" content="Kurzfassung zum Inhalt der Seite"/>
<meta name="keywords" content="mdlug,Magdeburg,Linux,Group,Vorlage"/>
<meta name="revisit-after" content="14 days"/>
<meta name="DC.Subject" content="Betreff der Seite (kurz halten)"/>
<meta name="DC.Description" content="Kurzfassung zum Inhalt der Seite"/>
<meta name="DC.Identifier" content="http://www.mdlug.de/"/>
<meta name="DC.Language" content="de"/>
<!--#include virtual="/includes/styles.html" -->
</head>

<body>
<!--#include virtual="/includes/header.html" -->

<h1>Vorlage für index.shtml</h1>
<p>
	Hier (zwischen header und footer include) kannst du deinen Kram 
	rein schreiben.
	Vergiß bitte nicht, auch die meta tags im <i>head</i> und den
	den <i>title</i> anzupassen.
</p>

<!--#include virtual="/includes/footer.html" -->
<div id="menu">
	<!--#include virtual="menu.html" -->
</div>
</body>
</html>

Wie dem aufmerksamen Leser sicherlich nicht entgangen ist, wird das Navigationsmenu für eine Webseite über die SSI Anweisung <!--#include virtual="menu.html" --> geladen. menu.html selbst wird für jeden Ordner aus der Datei menu.xml in den in Frage kommenden Ordnern und der Applikation sitemenu erzeugt. Die Applikation kann von unserem Download-Archiv (/download/web/) heruntergeladen werden. Informationen zur Installation/Nutzung findet man in der Datei sitemenu.README.

Das Programm sucht im Start-Ordner nach der Datei menu.xml, welche zum Haupt-Menu verarbeitet wird (Format: siehe menu.dtd). In dieser Datei sind sogenannte items aufgelistet, die jeweils einen Menu-Punkt repräsentieren. Enthält ein item einen Verweis auf ein Unterordner (tag dir), wird im entsprechenden Unterordner wiederum nach einer menu.xml gesucht, und falls vorhanden diese wieder auf die gleiche Art und Weise weiterverarbeitet und das so generierte Menu als Untermenu für den aktuellen Menu-Punkt eingefügt. Wird der angegebenen Ordner nicht gefunden und wurde nicht das Attribut traverse="false" angegeben, wird dies mit einer Warnung quittiert und der jeweilige Eintrag bei der weiteren Verarbeitung nicht weiter berücksichtigt.

Wurden alle gefundenen menu.xml Dateien verarbeitet, wird aus ihnen eine Datei menu-full.xml (enthält komplette Menu-Struktur) erzeugt und im Start-Ordner abgelegt. Aus dieser Datei wird für alle Ordner, in denen eine menu.xml Datei gefunden wurde, die Datei menu.html erzeugt. Die [Unter-]Menüs, die auf den jeweiligen Ordner (Pfad) zutreffen, sind dabei mit dem Attribut class="mon", der Verweis zum aktuellen Menu-Punkt mit dem Attribut class="selected" versehen worden.

Zuletzt wird noch eine Datei sitemap.html erzeugt, die falls es einen Ordner namens sitemap inkl. menu.xmlgibt, in diesem anderenfalls im Start-Ordner abgelegt wird.

Es ist wichtig zu wissen, daß nicht alle Verzeichnisse "blind" nach einer menu.xml durchsucht werden, sondern nur diejenigen, die in der gerade zu verarbeitenden menu.xml angegeben sind! Damit kann sehr gut gesteuert werden, was dann wirklich im Menu bzw. der Sitemap auftauchen soll.

Zur Veranschaulichung im folgenden ein kleines Beispiel:

Datei /tmp/test/menu.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<menu>
	<item>
		<label>Home</label>
		<desc>Homepage des MDLUG e.V.</desc>
		<dir name="/" traverse="false"/>
	</item>
	<item>
		<label>News</label>
		<desc>interne und externe Neuigkeiten</desc>
		<dir name="news"/>
	</item>
</menu>
Datei /tmp/test/news/menu.xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<menu>
	<item>
		<label>Verein</label>
		<desc>Neues innerhalb unseres Vereins</desc>
		<dir name="verein"/>
	</item>
	<item>
		<label>Anderes</label>
		<desc>andere Neuigkeiten</desc>
		<dir name="misc"/>
	</item>
</menu>
sitemenu -Dpath=/tmp/test erzeugt dann z.B. in /tmp/test/news/misc/ folgende menu.html
<!-- generated by sitemenu -->
<ul class="mon">
  <li>
    <p>
      <a href="/" title="Homepage des MDLUG e.V." >Home</a>
    </p>
  </li>
  <li>
    <p>
      <a href="/news/" title="interne und externe Neuigkeiten">News</a>
    </p>
    <ul class="mon">
      <li>
        <p>
          <a href="/news/verein/" 
              title="Neues innerhalb unseres Vereins">Verein</a>
        </p>
      </li>
      <li>
        <p>
          <a href="/news/misc/" title="andere Neuigkeiten"
              class="selected">Anderes</a>
        </p>
      </li>
    </ul>
  </li>
</ul>

Durch die geschickte Anwendung von Stylesheets (siehe /styles/, div#menu und #menu Einträge) wird diese Liste dann in Form eines Menüs visualisiert. Der relevante Part in jeder von unserer Vorlage abgeleiteteten HTML-Datei ist: 

<div id="menu">
	<!--#include virtual="menu.html" -->
</div>
Anmerkung

Prinzipiell ist die Generierung der Menu-Dateien lokal optional (zu Kontrollzwecken), da das entsprechende Script zur Aktualisierung der Webseite auf dem Server grundsätzlich die Dateien neu generiert und somit die bisherigen überschreibt...

Änderungen ins CVS-Repository übernehmen

Tja, prinzipiell gibt es hier nix besonderes zu beachten. Wie gehabt, in das jeweilige Verzeichnis wechseln, mit einem cvs update nochmal sichergehen, daß evtl. inzwischen von jemand anders geänderte Dateien aktualisiert werden und anschließend ein cvs commit (siehe auch CVS Parameter). Das könnte wie folgt aussehen: 

user.athome ~ > cd /tmp/mdlug.htdocs		
user.athome /tmp/mdlug.htdocs > cvs update
user.athome /tmp/mdlug.htdocs > cvs commit

Downloads bereitstellen

Derzeit gibt es prinzipiell zwei Möglichkeiten, selbiges zu tun:

  1. Auf dem Server einloggen und die Dateien/Ordner an die jeweilige Stelle verschieben (hat den Vorteil, daß die Permissions gleich korrekt gesetzt sind, es sei denn, jemand hat sein umask nicht auf dem default Wert).

  2. Per scp/sftp auf den Server an die jeweilige Stelle kopieren. Nachteil: Anpassung der Permissions.

Ein entsprechendes Web-Frontend ist in Planung, ist aber wie immmer abhängig von der Freizeit des Implementierenden (die i.d.R. gegen 0 konvergiert) :( .

Regeln

  1. Der "download"-Ordner ist ~www/sites/$siteName/download/

    Beispiel: ~www/sites/test.mdlug.de/download/

  2. Nicht-öffentliche Dateien/Ordner sind grundsätzlich unter ~www/sites/$siteName/download/intern/ abzulegen.

  3. Die Permissions für Verzeichnisse sollten auf 0775 (rwxrwxr-x) und für Dateien auf 0664 (rw-rw-r--) gesetzt werden

  4. Dateien sollten sinnvoll in Ordnern gruppiert werden.

Website aktualisieren

Ist eine unserer leichtesten Übungen:

  1. Auf dem Server per SSH einloggen

  2. Das Script /usr/local/etc/updateWebHtdocs.sh aufrufen. Falls was nicht in Ordnung ist, steht das da und sollte sich zu Gemüte geführt werden!

  3. Sich 1-2 Bierchen gönnen oder ins Bett gehen ;-).