$ ssh webuser@ictest.example.com ## 'webuser'-login in server testomgeving
$ su - ## switch naar 'root' user
# cd /usr/lib/cgi-bin/ic ## ga naar webserver's '/cgi-bin/ic'-directory
# ll vlink ## check op aanwezigheid van 'vlink'
-rwsr-xr-x 1 interchange interchange 7372 Oct 20 2010 vlink
# su -s /bin/bash interchange ## switch naar 'interchange' user en start bash-shell
$ alias ll='ls -l'; set -o vi ## enable commandline editing
$ cp -p vlink mycatalog ## -p: preserve permissions,owner,group
## -rwsr-xr-x interchange:interchange
$ ll mycatalog
-rwsr-xr-x 1 interchange interchange 7372 Oct 20 2010 mycatalog
=== 1.1 Toelichting 'vlink'-linkscript ===
Als de URL ictest.example.com/cgi-bin/ic/mycatalog///pagina-naam//
wordt opgevraagd,
geeft de Apache2 webserver op testserver 'ictest.example.com'
de vraag door aan het 'vlink'-linkscript
/cgi-bin/ic/**mycatalog** (/usr/lib/cgi-bin/ic/mycatalog).
Het 'vlink'-linkscript doet het volgende:
- opent de UNIX domain socket connectie naar de interchange daemon
- geeft alle data die hij van de Apache2 webserver heeft ontvangen door aan interchange ((Doorgegeven data: o.a. de 'CGI Extra Path Information' uit de URL. In het voorbeeld is dat: ///pagina-naam//))
- wacht tot interchange klaar is met het genereren van de HTML-pagina
- neemt de complete HTML-pagina aan van interchange
- sluist de HTML door naar de Apache2 webserver alsof het z'n eigen output is
Zie ook: [[linux:applicaties:interchange:ic-vlink-tlink2catalog]]
===== 2. Maak CATROOT in /var/lib/interchange/catalogs =====
Maak als gebruiker **interchange** in de **/var/lib/interchange/catalogs** directory
de CATROOT-directory aan voor catalogus 'mycatalog':
$ cd /var/lib/interchange/catalogs
$ mkdir mycatalog ## maak subdir voor catalogus 'mycatalog'
$ ll
drwxr-xr-x 2 interchange interchange 4096 May 17 10:55 mycatalog
=== 2.1 Toelichting CATROOT-directory ===
Elke catalogus heeft een CATROOT-directory nodig in de 'catalogs base dir' (/var/lib/interchange/catalogs).\\
De CATROOT-dir heeft de naam van de betreffende catalogus
(in dit voorbeeld dus 'mycatalog').\\
In de CATROOT-dir hangt alles wat voor de betreffende catalogus en het beheer ervan nodig is:
* IC-managed subdirectories
* logfiles
* evt. symlinks naar andere directories/files
Eigenaar, groep en rechten van de CATROOT-dir:\\
interchange:interchange, rwx voor eigenaar 'interchange'
===== 3. Maak de CATROOT subdirs 'session', 'etc' en 'tmp' =====
Maak als gebruiker **interchange** in CATROOT (/var/lib/interchange/catalogs/mycatalog)
de IC-managed subdirectories **session**, **etc** en **tmp**:
$ cd mycatalog ## ga naar CATROOT onder /var/lib/interchange/catalogs
$ mkdir session etc tmp; ll ## 'rwx' voor interchange, interchange:interchange
=== 3.1 Toelichting 'session', 'etc' en 'tmp' subdirs ===
De door de interchange daemon beheerde ('IC-managed') subdirectories 'session', 'etc' en 'tmp'
moeten door de 'interchange' gebruiker met de hand aangemaakt worden.
* 'session' bevat: IC sessie-files en lock-files m.b.t. de catalogus
* 'etc' bevat: statusinfo mb.t. de catalogus
* 'tmp' bevat: o.a. retired sessie-files
===== 4. Maak CATROOT/products/products.txt =====
Maak als gebruiker **interchange** in CATROOT de IC-managed 'database source'
subdirectory **products**
met daarin een simpele 'products'-database file (**products.txt**):
$ mkdir products ## maak CATROOT/products (default DB-source dir)
$ vi products/products.txt ## maak tijdelijke ('nep') DB-source file
SKU omschrijving prijs
1234 testitem 1.00
=== 4.1 Toelichting CATROOT/products/products.txt ===
Interchange is gebaseerd op het gebruik van een 'products database' i.v.m. de
combinatie website/webshop voor e-commerce doeleinden.
Zelfs als er geen products database gebruikt gaat worden moet er daarom toch
een 'database source'-directory (default: CATROOT/products)
met een 'database source'-file (default: CATROOT/products/products.txt) zijn.
De 'database source'-file kan een simpel 'TAB-delimited' ASCII-bestand zijn
met de naam 'products.txt' en bv. 3 velden per regel (zie voorbeeld).\\
Interchange zal hier zelf een echte database-file van maken, op basis van
wat hem bij installatie aan databases bekend is gemaakt
(default is: GDBM; products.txt -> products.gdbm).
===== 5. Registreer de catalogus in /var/lib/interchange/catalog.d =====
Registreer als gebruiker **interchange** de nieuwe catalogus d.m.v. het aanmaken van het
**mycatalog.cfg** configuratie-bestand in de directory **/var/lib/interchange/catalog.d**:
$ cd /var/lib/interchange/catalog.d
$ vi mycatalog.cfg ## maak de catalogus config.-file met 'Catalog'-directive regel
FullUrl yes
Catalog mycatalog /var/lib/interchange/catalogs/mycatalog ictest.example.com/cgi-bin/ic/mycatalog
=== 5.1 Toelichting catalogus registratie===
Interchange kan alleen geregistreerde catalogi managen.\\
Elke catalogus heeft hiervoor zijn eigen '//catalogus-naam//.cfg' bestand
in de /var/lib/interchange/catalog.d directory.\\
Het '//catalogus-naam//.cfg' bestand bevat minimaal een correcte
'Catalog'-directive regel voor het registreren van de betreffende catalogus.\\
Bij opstarten/herstarten zal de interchange daemon de aanwezige ".cfg" bestanden lezen
en de betreffende catalogi registreren.
De verplichte 'Catalog'-directive regel bevat 4 velden:
* directive voor het registreren van een catalogus: **Catalog**
* naam van de betreffende catalogus: bv. mycatalog
* CATROOT voor de betreffende catalogus: bv. /var/lib/interchange/catalogs/mycatalog
* route naar het 'vlink'-linkscript van de betreffende catalogus ('base catalog URL'): bv. /cgi-bin/ic/mycatalog
De 'FullUrl yes'-directive regel is optioneel.\\
Deze regel is nodig om vermelding van de fully qualified hostname
in het 4e veld van de 'Catalog'-directive regel
(de 'base catalog URL') gehonoreerd te krijgen.
((Default: geen 'FullUrl' regel -> hostname vermelding wordt genegeerd))\\
Op basis van de hostname+'vlink'-naam combinatie kan de catalogus op unieke wijze
ge_i:dentificeerd worden.
4e veld van 'Catalog'-directive regel:\\
* indien FullUrl regel ontbreekt (=default) of bij 'FullUrl no':\\ /cgi-bin/ic///catalogus-naam// (/cgi-bin/ic/mycatalog)
* indien 'FullUrl yes':\\ //hostname-fqdn///cgi-bin/ic///catalogus-naam// (ictest.example.com/cgi-bin/ic/mycatalog)
===== 6. Configureer de catalogus via CATROOT/catalog.cfg =====
Maak als gebruiker **interchange** het catalogus-specifieke configuratie-bestand **catalog.cfg**
in de CATROOT-directory van catalogus 'mycatalog' (/var/lib/interchange/catalogs/mycatalog):
$ cd /var/lib/interchange/catalogs/mycatalog ## ga naar CATROOT
$ vi catalog.cfg ## maak catalog.cfg met catalogus-specifieke directive regels
VendURL http://ictest.example.com/cgi-bin/ic/mycatalog
SecureURL http://ictest.example.com/cgi-bin/ic/mycatalog
Database products products.txt TAB
ErrorFile mycatalog-error.log
=== 6.1 Toelichting catalogus configuratie ===
Zet catalogus-specifieke directives in het configuratie-bestand **catalog.cfg**
in de CATROOT-directory van de betreffende catalogus.\\
Bij opstarten/herstarten zal de interchange daemon zal dit bestand gebruiken
om de catalogus te configureren.
Benodigde basis-directives in catalog.cfg:
* verplicht: **VendURL**: base catalog URL voor http (route naar 'vlink' voor de betreffende catalogus)
* verplicht: **SecureURL**: URL voor https (=VendURL, als https niet wordt gebruikt)
* verplicht: **Database**: table_name ('products'), table_source_file ('products.txt'), table_type ('TAB')
* optioneel: **ErrorFile**: relatieve padnaam naar catalogus-specifieke error logfile (-> maakt CATROOT///catalogus-naam//-error.log)
===== 7. Maak testfile CATROOT/pages/index.html =====
Maak als gebruiker **interchange** een CATROOT/pages subdirectory aan voor webpagina's.\\
Maak in CATROOT/pages een **index.html** testbestandje aan.
$ mkdir pages
$ vi index.html
Mycatalog: Welkom!
=== 7.1 Toelichting bij CATROOT/pages/index.html ===
Interchange verwacht dat de (HTML) webpagina's in de CATROOT/**pages** directory zullen staan.
((In Interchange is CATROOT/pages de default **PageDir**.\\ Zie verder: documentatie over PageDir-directive bij ICDevGroup: http://www.icdevgroup.org/docs/confs/index.html ))
===== 8. Restart Interchange en test resultaat in webbrowser =====
Restart de interchange daemon om de catalogus te laten registreren en configureren.\\
Voer het commando uit als gebruiker **interchange** (dus niet als 'root').
$ /etc/init.d/interchange restart
Restarting Interchange Server: interchange.
...
...
Configuring catalog mycatalog...done.
Interchange server started in UNIX mode(s) (process id 4280)
Vraag op het lokale systeem met de webbrowser de testpagina op
via de URL:\\
//hostname-fqdn///cgi-bin/ic///catalogus-naam///**index.html**
(ictest.example.com/cgi-bin/ic/mycatalog/index.html)
=== 8.1 Troubleshooting ===
Als dit niet goed gaat:
* bestudeer de foutmelding (van interchange en/of de webbrowser)
en check dan als gebruiker **interchange**:
* interchange error-log: /var/log/interchange/error.log
* catalogus error-log: CATROOT/mycatalog-error.log
* catalogus registratie-bestand: /var/lib/interchange/catalog.d/mycatalog.cfg
* catalogus configuratie-bestand: /var/lib/interchange/catalogs/mycatalog/catalog.cfg
N.B.: De interchange daemon zal een wijziging aan een registratie/configuratie-bestand niet automatisch opmerken en doorvoeren.\\
Om de configuratie (van alle catalogi) te testen terwijl de interchange daemon loopt:\\
* gebruik het commando: ((Voor alle opties van het 'interchange'-commando (/usr/sbin/interchange): zie de manpage.)) /usr/sbin/interchange --test
Er zijn twee manieren om een wijziging door te voeren:
- herstart de interchange daemon met het commando: /etc/init.d/interchange restart (dit heeft effect op **alle** catalogi die door de daemon worden beheerd: de daemon wordt gestopt en herstart; bij de 'server startup' worden alle catalogi opnieuw geconfigureerd) ((Meldt in logfile /var/log/interchange/error.log onder meer: 'STOP server', 'Removed catalog //catalogus-naam//, 'Config //catalogus-naam// at server startup' en 'START server'.))
- gebruik het commando: /usr/sbin/interchange --reconfig=mycatalog (dit heeft alleen effect op catalogus 'mycatalog': de daemon wordt niet gestopt, maar gedwongen de configuratie-bestanden van de betreffende catalogus opnieuw te bestuderen en uit te voeren) ((Meldt in logfile /var/log/interchange/error.log: 'Config //catalogus-naam// from running server (//process-id//)' en 'Reconfig of //catalogus-naam// successful.'))
===== 9. Speciale cataloguspagina CATROOT/special_pages/missing.html =====
In de catalogus-configuratie is nog niet geregeld wat er moet gebeuren als de opgegeven URL
niet leidt tot een bestaande cataloguspagina.\\
Voor de interchange daemon zal dit leiden tot een foutconditie ('script error'),
die wordt doorgegeven aan de Apache2 webserver.\\
Het gevolg is dat in de webbrowser een '500 Internal Server Error'-pagina verschijnt.
Met de **SpecialPage**-directive in CATROOT/catalog.cfg kan
worden geregeld dat in zo'n geval een speciale cataloguspagina ('missing.html') wordt getoond.\\
De standaard plek voor deze speciale pagina is in de directory: CATROOT/special_pages
Maak als gebruiker **interchange** de 'CATROOT/special_pages' directory
en het bestand 'missing.html'.\\
Wijzig dan CATROOT/catalog.cfg en herstart de interchange daemon:\\
$ su - ## switch naar 'root' user
# su -s /bin/bash interchange ## switch naar 'interchange' user en start 'bash'-shell
$ alias ll='ls -l'; set -o vi
$ cd /var/lib/interchange/catalogs/mycatalog ## ga naar CATROOT
$ mkdir special_pages ## maak 'special_pages' subdir
$ vi special_pages/missing.html ## maak HTML-pagina met eigen tekst
Pagina werd niet gevonden
... aanwijzingen wat nu te doen ...
$ vi catalog.cfg ## wijzig catalog.cfg
VendURL ...
SecureURL ...
Database ...
SpecialPage missing special_pages/missing.html ## <--- toegevoegde regel
ErrorFile ...
$ /etc/init.d/interchange restart ## restart interchange daemon
$ exit ## logout 'interchange' user
# exit ## logout 'root' user
$ ## terug in account van 'webuser'
Check het resultaat met de webbrowser. Test zowel correcte als incorrecte/incomplete URLs.
Een correcte URL is een URL die een bestaande cataloguspagina opvraagt.\\
Correcte URL in de huidige configuratie: ictest.example.com/cgi-bin/ic/mycatalog/index.html
=== 9.1 Toelichting 'SpecialPage' directive ===
De '**SpecialPage**'-directive regelt op catalogus-niveau wat er moet gebeuren als een
opgevraagde URL niet leidt naar een pagina van de betreffende catalogus.\\
De 'SpecialPage'-directive regel bestaat uit 3 velden ((Zie: documentatie op de ICDevGroup website: http://www.icdevgroup.org/docs/confs/index.html)):\\
- de directive: **SpecialPage**
- het 'special page' type: bv. 'missing'
- de padnaam van het 'special page' bestand gerekend vanaf CATROOT: bv. 'special_pages/missing.html'
===== 10. Automatisch laten zoeken naar 'index.html' =====
In de huidige configuratie leidt het gebruik van de 'base catalog URL'
(ictest.example.com/cgi-bin/ic/mycatalog)
tot het tonen van 'CATROOT/special_pages/missing.html'.\\
Het zou plezieriger zijn als automatisch de index-pagina van de catalogus
(CATROOT/pages/index.html) getoond zou worden.
Door de directives **SpecialPage** en **DirectoryIndex** te gebruiken
in het 'catalog.cfg' configuratie-bestand
kan het zoeken naar 'index.html' in CATROOT/pages en in subdirectories daarvan
worden geautomatiseerd.
Wijzig als gebruiker **interchange** CATROOT/catalog.cfg en herstart daarna de interchange daemon:\\
$ su - ## switch naar 'root' user
# su -s /bin/bash interchange ## switch naar 'interchange' user en start 'bash'-shell
$ alias ll='ls -l'; set -o vi
$ cd /var/lib/interchange/catalogs/mycatalog ## ga naar CATROOT
$ vi catalog.cfg
VendURL ...
SecureURL ...
Database ...
SpecialPage missing special_pages/missing.html
SpecialPage catalog index.html ## <--- toegevoegde regel
DirectoryIndex index.html ## <--- toegevoegde regel
ErrorFile ...
$ /etc/init.d/interchange restart ## restart interchange daemon
$ exit ## logout 'interchange' user
# exit ## logout 'root' user
$ ## terug in home-dir van 'webuser'
Check het resultaat met de webbrowser.\\
Gebruik als URL de 'base catalog URL': ictest.example.com/cgi-bin/ic/**mycatalog**
=== 10.1 Toelichting 'SpecialPage' en 'DirectoryIndex' directives ===
De regel '**SpecialPage catalog index.html**' zorgt ervoor dat, als de catalogus wordt opgevraagd
met uitsluitend de 'base catalog URL' (ictest.example.com/cgi-bin/ic/mycatalog),
er automatisch '/index.html' aan de URL wordt toegevoegd.\\
Hierdoor wordt er door Interchange automatisch gezocht naar CATROOT/pages/index.html
De '**DirectoryIndex**'-directive regelt op subdirectory-niveau
wat de standaardpagina is voor subdirectories onder
CATROOT/pages/ als de URL eindigt op '//subdir-naam//'.\\
De 'DirectoryIndex'-directive regel bestaat uit 2 velden:\\
- de directive: **DirectoryIndex**
- de paginanaam: index.html
De regel '**DirectoryIndex index.html**' zorgt ervoor dat, als
de URL ictest.example.com/cgi-bin/ic/mycatalog///subdir-naam// wordt opgevraagd,
er automatisch '/index.html' aan de URL wordt toegevoegd.\\
Hierdoor wordt er door Interchange automatisch gezocht naar CATROOT/pages///subdir-naam///index.html
===== 11. De 'Base Catalog URL' inkorten =====
'Base Catalog URL' in bovenstaande voorbeelden: ictest.example.com**/cgi-bin/ic/mycatalog**\\
Gewenste 'Base Catalog URL': ictest.example.com**/ic**
Inkorten **/cgi-bin/ic/mycatalog -> /ic** vereist:
* aanpassen van de Apache2 configuratie van de testserver en
* aanpassen van de Interchange registratie en configuratie van de 'mycatalog' catalogus.
Zie onderstaande 4 stappen.
==== 11.1 Aanpassen ScriptAlias in Apache2 config.file ====
Voeg als gebruiker **root** in /etc/apache2/sites-available///server-naam//
een ScriptAlias toe voor de nieuwe situatie:
$ su - ## switch naar 'root' user
# vi /etc/apache2/sites-available/ictest ## wijzig bestand van 'ictest' testserver
...
...
ScriptAlias /cgi-bin /usr/lib/cgi-bin
ScriptAlias /ic /usr/lib/cgi-bin/ic/mycatalog ## <--- toegevoegde regel
...
...
# apache2ctl configtest ## run Apache2 Configtest
# /etc/init.d/apache2 restart ## restart Apache2 indien configtest OK
# tail /var/log/apache2/error.log ## check Apache2 error.log
==== 11.2 Aanpassen catalogus registratie ====
Pas als gebruiker **interchange** in /var/lib/interchange/catalog.d/mycatalog.cfg het 4e veld van de 'Catalog'-directive regel aan:
# su -s /bin/bash interchange ## switch als 'root' naar 'interchange' user
$ alias ll='ls -l'; set -o vi
$ cd /var/lib/interchange/catalog.d
$ cat mycatalog.cfg ## check huidige configuratie
FullUrl yes
Catalog mycatalog /var/lib/interchange/catalogs/mycatalog ictest.example.com/cgi-bin/ic/mycatalog
$ vi mycatalog.cfg ## wijzig 4e veld van 'Catalog'-directive
FullUrl yes
Catalog mycatalog /var/lib/interchange/catalogs/mycatalog ictest.example.com/ic
==== 11.3 Aanpassen catalogus configuratie in CATROOT ====
Wijzig als gebruiker **interchange** de directive-regels 'VendURL' en 'SecureURL' in /var/lib/interchange/catalogs/mycatalog/catalog.cfg:
$ cd /var/lib/interchange/catalogs/mycatalog ## ga naar CATROOT
$ cat catalog.cfg ## check huidige configuratie
VendURL http://ictest.example.com/cgi-bin/ic/mycatalog
SecureURL http://ictest.example.com/cgi-bin/ic/mycatalog
...
...
$ vi catalog.cfg ## wijzig configuratie
VendURL http://ictest.example.com/ic
SecureURL http://ictest.example.com/ic
...
...
==== 11.4 Interchange herstarten en resultaat testen ====
Het wijzigen van registratie/configuratie vereist herstarten van de interchange daemon.\\
Voer dit uit als gebruiker **interchange**:
$ /etc/init.d/interchange restart
$ tail /var/log/interchange/error.log
$ tail /var/lib/interchange/catalogs/mycatalog/mycatalog-error.log
$ exit ## logout 'interchange' user
# exit ## logout 'root' user
$ ## terug in account van 'webuser'
Check het resultaat met de webbrowser.\\
Gebruik als URL: ictest.example.com/ic/index.html\\
(of als de 'SpecialPage'-directive is toegepast: ictest.example.com/ic)
===== 12. Bestanden verplaatsen naar de home-dir van een user =====
Het is geen probleem om de IC-managed HTML-bestanden (de CATROOT/pages directory)
uit CATROOT te verplaatsen naar de home-dir van een gewone gebruiker zoals 'webuser'.
Dit biedt de mogelijkheid om ze door de betreffende gebruiker te laten beheren
(bv. met een versiebeheersysteem zoals 'Git').
((Andere kandidaten voor verplaatsing zijn bv.: CATROOT/special_pages, CATROOT/includes en CATROOT/usertags))
Voorwaarden:\\
- gebruiker 'interchange' heeft leesrecht op de betreffende subdirectories en bestanden
- de betreffende CATROOT///**subdir**// wordt vervangen door een CATROOT///**symlink**// met de naam van de oorspronkelijke IC-managed subdirectory
**Voorbeeld: CATROOT/pages -> /home/webuser/www/ic/pages**
==== 12.1 Verplaats CATROOT/pages naar 'www/ic' subdir van 'webuser' ====
Maak als gebruiker **root** een nieuwe 'www/ic' subdirectory
in de home-directory van gebruiker 'webuser' en verplaats de inhoud van CATROOT/pages:
$ su - ## switch naar 'root' user
# cd /home/webuser ## ga naar home-dir van 'webuser'
# mkdir -p www/ic ## maak 'www/ic/' subdir
# mv /var/lib/interchange/catalogs/mycatalog/pages www/ic/ ## verplaats CATROOT/pages
# ll -R www/ic/pages ## check resultaat
==== 12.2 Wijzig eigendom en rechten ====
Rechten en eigendom voor directory /home/webuser/www en zijn subdirectories & bestanden: \\
leesrecht: voor iedereen; schrijfrecht: alleen voor eigenaar 'webuser',
de beheerder van de webpagina's\\
* dirs 755 (drwxr-xr-x) webuser:webuser
* files 644 (-rw-r--r--) webuser:webuser
Voer als gebruiker **root** "chown" en "chmod" commando's uit om rechten, uid en gid goed te zetten:\\
# find www -exec chown webuser:webuser {} \; ## wijzig uid en gid
# find www -type d -exec chmod 755 {} \; ## wijzig rechten op directories (drwxr-xr-x)
# find www -type f -exec chmod 644 {} \; ## wijzig rechten op bestanden (-rw-r--r--)
==== 12.3 Maak de CATROOT/pages symlink ====
Maak als gebruiker **interchange** de 'CATROOT/pages' symlink, zodat Interchange de nieuwe 'pages' directory kan bereiken:
# su -s /bin/bash interchange ## switch naar 'interchange' user en start 'bash'-shell
$ alias ll='ls -l'; set -o vi
$ cd /var/lib/interchange/catalogs/mycatalog ## ga naar CATROOT
$ ln -s /home/webuser/www/ic/pages . ## maak nieuwe symlink 'pages'
$ ll pages ## check resultaat
$ exit ## logout 'interchange' user
# exit ## logout 'root' user
$ ## terug in account van 'webuser'
==== 12.4 Check resultaat ====
Check het resultaat met de webbrowser.\\
Alle cataloguspagina's en evt. 'special pages' moeten correct te zien zijn.
===== 13. Basis-Catalogus verder ontwikkelen ====
Meer informatie over het bouwen van een simpele webshop is te vinden op
de website van de Interchange Development Group, in de 'Catalog Tutorial'
http://www.icdevgroup.org/docs/iccattut/index.html
vanaf het hoofdstuk 'Page Templates'.
====== . ======
Copyright (c) 2013 Integrated Services; Tux4u.nl\\
Author: M.Waldorp-Bonk; ic-catalog-howto.txt 2013-05-21; 2013-07-17