MiniMate - An Administration Tool for MiniVend
**********************************************

MiniMate, formerly called MaxiVend, is a web frontend for MiniVend. It has
been written by Mike Heins, also the author of MiniVend. With MiniMate you
can easily: 
     
   * Edit MiniVend databases
   * Upload/Download pages and other files (e.g. images)
   * ...

License
*******

MiniMate is distributed under the terms of the GPL (URL:
http://www.gnu.org/copyleft/gpl.html).

Homepage, Version and Download
******************************

Up-to-date informations about MiniMate are available from 
http://www.linuxia.net/minimate/. To stay tuned with current developments
contact please <racke@linuxia.net>.

The version of MiniMate is `3.14.0.3'. An archive of this version is
available from this site (URL: minimate.tar.gz) and from ftp.minivend.com (URL:
ftp://ftp.minivend.com/pub/minimate/minimate.tar.gz) (daily updates) and can
be used on all operating systems.

MiniVend 3.12 and higher is required to running MiniMate.

Demonstration
*************

MiniMate can be tested at the following locations: 

http://www.linuxia.net/mmdemo/simple/admin/menu (URL: http://www.linuxia.net/mmdemo/simple/admin/menu)

http://www.linuxia.net/mmdemo/simple/config/menu (URL: http://www.linuxia.net/mmdemo/simple/config/menu)

Installation
************

First unpack the sources in an arbitrary directory (not in the MiniVend
installation directory):

racke@linuxia.net:/tmp > gzip -cd minimate.tar.gz | tar -xf -
On a computer running Linux or with GNU tar the following is sufficient:

racke@linuxia.net:/tmp > tar -xzf minimate.tar.gz
After unpacking the sources change to the directory `MiniMate-3.14.0.3'.
Then run the `install' script with the installation directory of MiniVend as
parameter:

racke@linuxia.net:/tmp/MiniMate-3.14.0.3 > perl install ~/mvend
The script checks the existence of `minivend.cfg', creates a subdirectory `
lib/MiniMate' in the installation directory and copies the necessary files
into this directory.

Now you need to edit your `minivend.cfg' and add the following line: 


#include lib/MiniMate/minimate.cfg

The administration tool is available after a restart of MiniVend. You can
access it from every catalog. Use the pages `admin/menu.html' (with frames)
resp. `config/menu.html' (without frames). For example, the URL to access
the catalog is `http://www.linuxia.net/cgi-bin/simple'. Then the simpler
variant of MiniMate can be found at `
http://www.linuxia.net/cgi-bin/simple/config/menu'.

Please note that currently you are responsible for protecting the
administration tool against access from other people.

Problems
========

Inserting data containing single quotes fails
---------------------------------------------

This error occurs with MiniVend 3.11. Please upgrade.

`Term::ReadKey' misses `resize'
-------------------------------


Can't exec "resize": No such file or directory at /usr/lib/perl5/site_perl/Term/ReadKey.pm line 305.
Unable to get Terminal Size. The TIOCGWINSZ ioctl didn't work.
The COLUMNS and LINES environment variables didn't work.
The resize program didn't work. at /usr/lib/perl5/site_perl/Term/ReadKey.pm line 323.
make: *** No targets.  Stop.

This is a known problem with Perl and MakeMaker on Solaris. There are
reports for this problem on Linux (Slackware and SuSE) where X isn't
installed. Mike Heins suggested the following workaround:


    export LINES=24 COLUMNS=80

or (for Korn and similar shells)


    setenv LINES=24
    setenv COLUMNS=80

Alternatively, you may uninstall `Term::ReadKey'.

Edit Databases Causes Runtime Error
-----------------------------------

Pumin Wuvanich reported this problem. I was not able to reproduce it. Maybe
it is related to subcatalogs.

206.111.118.118 4pedfCqg:206.111.118.118 - [30/June/1999:12:30:14 -0700] 
test01 /cgi-bin/simple/config/dbedit Runtime error: Can't use string 
("2ndDayAir") as a HASH ref while "strict refs" in use at (eval 68) line 22.
>
206.111.118.118 4pedfCqg:206.111.118.118 - [30/June/1999:12:30:31 -0700] 
test01 /cgi-bin/simple/config/dbedit Runtime error: Can't use string 
("Ground") as a HASH ref while "strict refs" in use at (eval 68) line 22.
>
206.111.118.118 4pedfCqg:206.111.118.118 - [30/June/1999:12:31:00 -0700] 
test01 /cgi-bin/simple/config/dbedit Runtime error: Can't use string 
("locale") as a HASH ref while "strict refs" in use at (eval 68) line 22.
>


Security
********

The administration tool should only accessible for the shop owner.

Access Control with Apache
==========================

First configure Apache to deny access to the MiniMate pages without a
password:


<LocationMatch /cgi-bin/simple/+(admin/config)>
AuthType Basic
AuthUserFile /home/minivend/users
AuthName "MiniVend Administration"
require valid-user
</LocationMatch>

The plus sign is necessary to protect against access with the URL `
/cgi-bin/simple//config/menu.html'. Enter the user name of the shop owner in
the catalog configuration file `catalog.cfg':

RemoteUser minivend
For access to the MiniMate pages by the shop owner create empty files named `
.access' in the directories `config' and `admin':

racke@linuxia.net:~ > rm -f /home/minivend/lib/MiniMate/pages/config/.access
racke@linuxia.net:~ > touch /home/minivend/lib/MiniMate/pages/config/.access
racke@linuxia.net:~ > rm -f /home/minivend/lib/MiniMate/pages/admin/.access    
racke@linuxia.net:~ > touch /home/minivend/lib/MiniMate/pages/admin/.access

Create files named `.access_gate' in the same directories to allow access by
the user authentified through Apache:

*: [perl arg="config" interpolate=1]
        return 1 if $Safe{config}{RemoteUser} eq q{[data session user]};
        return 0;
    [/perl]


Access Through the Internal Web Server
======================================

Create an non-empty file `.access' in all directories containing MiniMate
pages.All those pages are accessible only by the shop owner defined by the
catalog configuration directives `RemoteUser' and `Password':

Variable    MV_NO_CRYPT 1
RemoteUser  demo
Password    Gu3109n

The shop owner access the MiniMate pages via the internal web server
provided by the MiniVend daemon: 

http://www.linuxia.net:7786/simple/config/menu

MiniMate Usage
**************

Upload Images
=============

Uploaded files could stored only below the catalog directory. Usually you
deny access to files within the catalog directory to the web server due to
security and data protection reasons. You have to break this golden rule to
allow image upload with MiniMate. You should permit access only to the
subdirectory with the images.

For image upload please choose on the page `config/menu' "Upload other
files".

Internationalization
********************

The internationalization of MiniMate is in progress. However, additional
volunteers are needed.

A Russian and a German translation has been already made.

List of MiniMate Pages
**********************


`config/menu'
     
     start page for the frameless version

`config/upload_other'
     
       upload/download of arbitrary files


MiniMate for Developers
***********************

MiniMate Extensions to the MML
==============================


`directive_value' NAME [PARSEVARS]
     
     Expands to the value of the configuration directive NAME. If PARSEVARS
     has a truth value, the variables within the value are replaced by their
     value.


Undocumented Tags
-----------------

   * base-url
   * check-upload
   * counter
   * db_columns
   * dbinfo
   * display
   * display_directive
   * e
   * export-database
   * global-value
   * if-key-exists
   * if-sql
   * import_fields
   * list_directives
   * list_pages
   * newer
   * quick_table
   * read_serial
   * reconfigure
   * rotate-database
   * rotate-table
   * rotate_file
   * row-edit
   * send-help
   * set-alias
   * set-click
   * substitute
   * title-bar
   * unconfigure
   * version
   * widget
   * write_config

TODO list
*********

   * Bug Fixes 
          
        * Fix `install' script
        * Edit Databases Causes Runtime Error
   * Integrate help pages
   * Internationalization
   * Secure installation out of the box
   * Use <H?> instead of font tags
   * Change `admin/menu' file uploads to the internal variety instead of
     using external `mv_upload' program.
   * Browse existing files (upload other files).
   * Consider version control systems for page upload.
   * Validate HTML output.
   * Compare with ShopAdmin

Changes
*******


8. August 99
     
     German translation from Birgitt Funk added.

5. August 99
     
     Russian translation from Alexei Yakimovich added.

28. July 99
     
     MiniMate pages prepared for localization.

26. July 99
     
     Fixed searching for records (`config/dbedit').

13. July 99
     
     Help for configuration directives shows up now.

6. July 99
     
     Fixed `Makefile.PL' for Win32 systems. Rewrote the `install' script.

29. June 99
     
     Useless import of `Data::Dumper' removed.

16. June 99
     
     Support for internationalization added.


Credits
*******

Mike Heins for writing MaxiVend in the first place and being a invaluable
resource for tips and bug fixes.

Betty Chung for preparing the MiniMate pages for localization.

Alexei Yakimovich for the Russian translation.

Birgitt Funk for the German translation.

Stephen M. LaBar, Jr. for his help to make `Makefile.PL' working on Win32
systems.

Kaare Rasmussen and Robert Hutchinson for reporting the `resize' problem and
again Mike Heins for the workaround.

Bob Jordan for reporting the `Data::Dumper' problem.

Waldemar Gerr for his suggestion on documenting the installation.

Marci Beedle for reporting his problem with the documentation in respect of
an MiniMate URL.

History
*******


12. July 99
     
     Version 3.14.0.3 released

30. June 99
     
     Version 3.14.0.2 released

29. June 99
     
     Version 3.14.0.1 released

