Dit document beschrijft de basisstappen voor het opzetten van een Interchange Catalogus ¹⁾.

In de voorbeelden wordt op testserver ictest.example.com de catalogus mycatalog ingericht en getest.

Tot slot wordt beschreven hoe de webpagina's van deze catalogus vanuit de zgn. 'CATROOT-directory' verplaatst kunnen worden naar de home-directory van gebruiker webuser, zodat deze gebruiker de webpagina's zelf kan beheren (bv. met een versiebeheersysteem zoals 'Git').

Dit document is gebaseerd op Interchange versie 5.7.6 (Debian pakket) ²⁾ .

• Server 'ictest' ingericht (ictest.example.com)
  
• Apache2 geconfigureerd
  
• Interchange software (Debian pakket) ge_i:nstalleerd
  
• gebruikers: 'webuser' en 'interchange' ³⁾
• Interchange daemon gestart ⁴⁾
• de Interchange daemon heeft twee 'listening' UNIX domain sockets gemaakt ⁵⁾

Gebruiker interchange moet op de testserver 8 stappen uitvoeren:

1. maak 'vlink'-linkscript: /usr/lib/cgi-bin/ic/mycatalog
2. maak 'CATROOT-directory': /var/lib/interchange/catalogs/mycatalog
3. maak IC-managed subdirectories: CATROOT/session, CATROOT/etc, CATROOT/tmp
4. maak 'database source' directory en file: CATROOT/products/products.txt
5. maak catalogus registratie-bestand: /var/lib/interchange/catalog.d/mycatalog.cfg
6. maak catalogus configuratie-bestand: CATROOT/catalog.cfg
7. maak webpagina's-directory met testpagina: CATROOT/pages/index.html
8. restart interchange daemon

De stappen worden hieronder stuk voor stuk besproken.
Het resultaat wordt steeds getest met een webbrowser op het lokale systeem.

Voor de Apache2 webserver is het 'vlink'-linkscript /cgi-bin/ic/vlink-naam het pad naar de interchange catalogus.
De zgn. 'Base Catalog URL' ziet eruit als: ictest.example.com/cgi-bin/ic/vlink-naam
Elke catalogus heeft zijn eigen 'vlink'-linkscript met de naam van de catalogus (in het voorbeeld heet de 'vlink' daarom: 'mycatalog').

Login in de testserver ⁶⁾ en switch naar het 'root'-account ⁷⁾ .
Maak als gebruiker interchange in de /usr/lib/cgi-bin/ic directory het 'vlink'-linkscript aan voor de nieuwe catalogus 'mycatalog':

$ 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

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:

1. opent de UNIX domain socket connectie naar de interchange daemon
2. geeft alle data die hij van de Apache2 webserver heeft ontvangen door aan interchange ⁸⁾
3. wacht tot interchange klaar is met het genereren van de HTML-pagina
4. neemt de complete HTML-pagina aan van interchange
5. sluist de HTML door naar de Apache2 webserver alsof het z'n eigen output is

Zie ook: ic-vlink-tlink2catalog

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

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'

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

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

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

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).

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

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. ⁹⁾
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)

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

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)

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

<html>
<body>

<h1>Mycatalog: Welkom!</h1>

</body>
</html>

Interchange verwacht dat de (HTML) webpagina's in de CATROOT/pages directory zullen staan. ¹⁰⁾

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)

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: ¹¹⁾

  /usr/sbin/interchange --test

Er zijn twee manieren om een wijziging door te voeren:

1. 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) ¹²⁾

2. 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) ¹³⁾

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
<html>
<body>

<h1>Pagina werd niet gevonden</h1>
<p>
... aanwijzingen wat nu te doen ...
</p>

</body>
</html>

$ 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

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 ¹⁴⁾:

1. de directive: SpecialPage
2. het 'special page' type: bv. 'missing'
3. de padnaam van het 'special page' bestand gerekend vanaf CATROOT: bv. 'special_pages/missing.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

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:

1. de directive: DirectoryIndex
2. 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

'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.

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
<Directory "/usr/lib/cgi-bin">
...
...
</Directory>

# 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

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

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
...
...

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)

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'). ¹⁵⁾

Voorwaarden:

1. gebruiker 'interchange' heeft leesrecht op de betreffende subdirectories en bestanden
2. 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

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

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--)

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'

Check het resultaat met de webbrowser.
Alle cataloguspagina's en evt. 'special pages' moeten correct te zien zijn.

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 © 2013 Integrated Services; Tux4u.nl
Author: M.Waldorp-Bonk; ic-catalog-howto.txt 2013-05-21; 2013-07-17