Introduction
Server Platform
   Installation
   Directory
   Configuration
   Operation
Application Server
Content Generation
Class Library API
Manual Index

next | previous

Maxscape Installation

The installation of Maxscape is quite easy. The installation process, if you are familiar with UNIX, will take about an hour. Most of the time will be taken by setting up the computer's operating system to meet Maxscape requirements. Once the server is setup, Maxscape needs to be configured. The following README.install is outdated, but gives an overview. The current release was build on Ubuntu UNIX.

README.install

1. INTRODUCTION
===============

Maxscape has been build on S.U.S.E, REDHAT and Solaris. The current
release is build on Ubuntu Linux. Any database, which is supported by
DBD/DBI might be fine. So far, Msql, Mysql and Orcale had been in use.

The distribution contains:

  - an integrated perl compiler
  - the famous apache daemon
  - Fast-CGI interface from open market
  - the apache mod_perl extension
  - the fast Mysql database
  - the analog HTTPD statistic tool
  - many modules from CPAN
  - ...

2. MANIFEST
===========

   maxscape-3.35-README.install        -  this file
   maxscape-3.35.tar.gz                -  Maxscape 3.35 tarfile

   maxscape-3.35-opt-1-linux.tar.gz       -  perl, apache, mysql, openssl, analog
   maxscape-3.35-opt-2-linux.tar.gz       -  ..

   maxscape-3.35-mysql-db-linux.tar.gz - Maxscape Mysql database files


3. SECURITY
===========

Here are only a few tips for Maxscape installations in unsecure environments:

  - During your first Maxscape installation
    do not connect your computer to an insecure network
  - READ the various sources about security.
  - only use SSH/SCP (secure shell/copy) to login/copy.
  - install as LESS as possible
  - DON'T install or enable telnet, ftp, rlogin, rsh, ...
  - inspect your inetd.conf.
  - only login to the Maxscape administration server via ssl (https://...)
    to hide the user identification, passwords, content a.s.o.
  - CHANGE all PASSWORDS after installation
  - do not develope on a production system
  - allways have a BACKUP of your system -:)


4. HARDWARE/OPERATING SYSTEM
============================

   Hardware

     For private use any 80586 PC is ok. For medium intranet sites a pentium or a
     multi processor PC will do it. Large sites should use a servers from SUN or HP..

   Server Cluster

     The maXscape platform could also be configured to operate on a cluster of dedicated
     maschines with database, file and proxy server.

   Operating System

     MaXscape must be installed on a linux or solaris OS. We recommend
     Linux REDHAT or S.U.S.E, but other Linux distributions may work, too.

   Operating System Software

     Prepare the hardware and the operating system of your computer.
     If you are going to install this software on a production system,
     install as less as possible and do not install X.

   Recommended Memory Space

     Recommended are 512 GB RAM. For loaded sites, especialy in conjunction
     with Oracle more are better.128 MB may work, but system performance will
     suffer, if memory page swapping happens.

   File Partitions

     Think about disks and partitioning. You need at least 500 MB disk
     space for the maxscape software and the base system. Add what your static
     documents (including images, downloads, a.s.o) and the database
     installation requires.

       estimated diskspace >= 'base system (perl, apache, db, ..) + maxscape'
                           +  'your database installation + database files'
                           +  'your static documents'

     You may give own partitions to the documents roots, the database files
     and special directories of your various application servers (see /etc/fstab).

       mount /dev/???? /opt/maxscape/3.35/server/'application server'/docs

     or (see file partition example):

       mount /dev/???? /opt/docs
       ln -s /opt/docs /opt/maxscape/3.35/server/'application server'/docs

     On SCSI drives the following example configuration may be sufficient.
     If Mysql is used instead of Oracle, much less storage is required for
     the database server installation and the database files:

     sda:
       /           1.5 GB   System-SW
       swap1       512 MB
       /usr        5   GB
       /opt        5   GB   Oracle-, Maxscape-SW
       /home       2GB      User-Home-Directories, Scratch f. Installation/Build
       /var/db1    2GB      Oracle-Daten
       /var/db2    2GB      -"-

     sdb:
        swap2      512MB
       /var/db3    2GB     -"-
       /var/db4    2GB     -"-



5. BASE SYSTEM INSTALLATION (example on linux with mysql)
=========================================================

For easy handling, cut the commands from this file and paste it to the
command line shell (tcsh is prefered in the Maxscape interactive shell
environment).


1)  Login as root.

       su -

2)  Change to the root directory and extract the base system (perl, apache,..)
    and the mysql database files from the distribution tar files (assuming
    '/tmp' contains the files). They are installed under the '/opt' directory.

      cd /
      tar zxvf /tmp/maxscape-3.35-opt-1-linux.tar.gz
      tar zxvf /tmp/maxscape-3.35-opt-2-linux.tar.gz

3)  Change to the MySql database files directory and extract the Maxscape
    MySql database files, if you want to use mysql.

      cd /opt/mysql
      mkdir var
      cd var
      tar zxvf /tmp/maxscape-3.35-mysql-db-linux.tar.gz

      # Issue the next command after creation of the mysql user. See later...
      chown -R mysql:mysql /opt/mysql/var  # after creation of the mysql user
                                           # see later...

3a) To install a new mysql database, an installation script is provided
    (/maxscape/sbin/install_db.mysql). Skip this point for your first
    installation.

3b) To create a new database instance for a application server, use the script
    (/maxscape/sbin/create_db.mysql). Skip this point for your first
    installation.

3c) The password of the 'mysql' user of the Mysql database is 'kfisxhhv'.
    The password of the user 'MaXscapeadm' of the Mysql database is
    'ktgiotfig'.


6. MAXSCAPE INSTALLATION
========================

1) Login as root

        su -

2)  Change to the directory, under which the Maxscape software should be
    installed. We recommend the '/opt' directory.

      cd /opt

    Make a directory 'maxscape':

      mkdir maxscape

    Make a directory named 3.35:

      cd maxscape
      mkdir 3.35

    Change to the Maxscape 3.35 server root directory:

      cd 3.35

3)  Extract the Maxscape distribution from the tar file (assuming
    '/tmp' contains the file).

      tar zxvf /tmp/maxscape-3.35.tar.gz

4)  Define the two shell environment variables PROJECT_NAME and PROJECT_HOME
    (tcsh example)

      setenv $PROJECT_NAME maxscape
      setenv $PROJECT_HOME /

5)  Create a unique Maxscape root path. This link could be used as an entry
    point to the Maxscape directory structure ('cd /maxscape' allways brings
    you to the maxscape root directory.

      ln -s /opt/maxscape/3.35 $PROJECT_HOME$PROJECT_NAME

6)  Read the README.license file. Only continue if you do accept the license.

      cd /maxscape
      less README.license

7)  Create required users & groups (mysql example).
    This script is an example and does not check if users already exist.
    If you add the users by hand, set the home directory of the maxscape
    account to:

      /maxscape/var/home/maxscape

    or execute (after inspection and possible adaption)

        # is only an example, see content
        /maxscape/sbin/create_maxscape_users.sh 
        # is only an example, see content
        /maxscape/sbin/create_mysql_user.sh

      or

        # is only an example, see content
        /maxscape/sbin/create_users

    The login shell should allways be a borne shell. '/etc/passwd' should
    look like:

      ...
      mysql:x:8100:8100::/maxscape/var/home/mysql:/bin/sh
      maxscape:x:8000:8000::/maxscape/var/home/maxscape:/bin/sh
      maxrun:x:8001:8000::/maxscape/var/home/maxrun:/bin/false
      super:x:0:8000::/maxscape/var/home/su:/bin/sh

      ...

    The '/etc/group' file may look like:

      ...
      maxscape:x:8000:maxscape
      mysql:x:8100:mysql
      ...


8)  Change the passwords for maxscape, super, mysql, ...

      passwd maxscape
      ..

      Note: For all created users passwords should remain disabled
      (this is the default). Usually these accounts are accessed
      via ssh (for remote administration) or via the su command
      (by super or root).

9)  Set the required permissions for maxscape, the database and the
    other tools:

      chown -R mysql:mysql /opt/mysql/var # (mysql)

10) Now 'cd /maxscape' and run 'make install'

    At the moment the only action of this script is a:

      chmod -R ogu+rwx /maxscape/var/tmp

11) Make a new session as user 'maxscape':

     su - maxscape

12) The distribution comes with a license for a trial and test version
    of Maxscape. To use this you need to name your server 'www.maxscape.com'
    having the IP address '192.168.0.90'. So, the following instructions
    only need to be processed, if you have obtained a Maxscape license for
    your site.

    If you have already obtained a Maxscape license for your site, install
    it, now. For this change to the maxscape root account and copy it to
    the /maxscape/etc directory:

      cd /maxscape
      cp /tmp/maxscape-3.35-License.'your site name' etc/License 

13) Adjust the apache configuration, i.e. edit /maxscape/etc/apache/httpd.conf
    and the apache configuration files of your various application server
    (/maxscape/server/'your unique application server id'/etc/httpd.conf).
    The Maxscape administration server (WebServer) and the Test server are
    preconfigured but you must set your site name. Consult the Maxscape,
    apache, FCGI, mod_perl, a.s.o. manuals for more information:

    The apache server configuration file (httpd.conf) is split into the
    generic and the application server specific parts. The later are included
    via the apache's include directive.  Assuming your site has the name
    'www.myscape.com' and runs the  Maxscape administration and test servers.
    (The application server on the port 80 named 'myscape' is disabled.)

      vi /maxscape/etc/apache/httpd.conf

        ...
        ...
        # Ports assigned to configured servers:

        # Maxscape administration server (WebServer):
        Port 2080
        Listen 2080

        # Maxscape server:
        Port 4711
        Listen 4711

        # 'your 1st application server' e.g. 'myscape' (default server):
        Port 80
        Listen 80
        ...
        ...

        include /maxscape/server/WebServer/etc/httpd.conf
        include /maxscape/server/MaXscape/etc/httpd.conf
        #include /maxscape/server/myscape/etc/httpd.conf


    Change the 'VirtualHost', 'ServerName', ... entries to their real
    names (change 'asus.local.net' to 'your site name') e.g.:

      vi /maxscape/server/WebServer/etc/httpd.conf

        <VirtualHost www.maxscape.com:2080>

          DocumentRoot           /maxscape/server/WebServer/docs
          ServerName             www.maxscape.com
          ServerAdmin            maxscape@maxscape.com
          ErrorLog               /maxscape/var/server/WebServer/logs/error
          ...
          ...


      vi /maxscape/server/MaXscape/etc/httpd.conf

        <VirtualHost www.maxscape.com:4711>
          ...
          DocumentRoot           /maxscape/server/MaXscape/docs
          ServerName             www.maxscape.com
          ServerAdmin            maxscape@maxscape.com
          ...
          ...

14) Edit the maxscape runtime system configuration file, to set up
    the database user identification and passwords for the configured
    application server. You need to change the user passwords of your
    database, also (not necessary if you use the Mysql database files,
    that comes with this distribution):

       vi /maxscape/etc/maxscape.cnf

         <maXscapeConfiguration>
          <hash>
           <item key="main">
           <!-- global variables                                            -->
            <hash>
             ...
             <item key="database::product">mysql</item>
             ...
            </hash>
           </item>
         
          <!-- application server database configuration                    -->

          <item key="Databases">
           <hash>

            <!-- maXscape administration server                             -->

            <item key="WebServer">         <!-- unique application server id-->
             <hash>
              <item key="Host">localhost</item>   <!-- do not touch         -->
              <item key="Id">WebServer</item> <!-- unique application server
                                                         database id        -->
              <item key="User">mysql</item>       <!-- database user        -->
              <item key="Passwd">kfisxhhv</item><!-- database password    -->
             </hash>
            </item>

           <!-- 'your application server' -->

           <item key="myserver">                  <!-- unique virtual
                                                       server id         -->
            <hash>
             <item key="host">localhost</item>    <!-- do not touch      -->
             <item key="id">mydatabase</item>     <!-- unique application server
                                                         database id       -->
             <item key="user">myuser</item>       <!-- database user     -->
             <item key="passwd">mypassword</item> <!-- database password -->
            </hash>
           </item>
           ...

15) If all went well till this point, the Maxscape server could be started,
    now. Start the server from your super session, if a application server
    is running below port 1024:

      su - su
      /maxscape/etc/init.d/maxscape start # (or start,restart,stop)

    will do the magic. If you see the following lines, your installation
    seems to be complete.

      Starting database...
      MySql Server Home=/opt/mysql/5.5.39/usr
      Starting apache HTTP server...
      Starting Maxscape at Di 3. Mai 23:55:37 MEST 2016 from /maxscape...

    To start Maxscape at boot time add the '/maxscape/etc/init.d/maxscape'
    script to your OS boot mechanism (e.g. /etc/init.d/*).

16) As a first test of the installation login as maxscape, change to
    the document root of the Maxscape administration server and invoke
    the servers FCGI mainloop script. The '-h' option gives a little help:

      su - maxscape
      cd /maxscape/server/WebServer/docs
      ./www.fcg [-h]

    If all went well, the Maxscape admin server homepage will appear:

      Content-Type: text/html

      <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
      <HTML>
      <HEAD>
      <TITLE>Maxscape Administration Server</TITLE>
      ...

17) Now, it should be possible to login to the maxscape administration
    server via a web browser (e.g. user 'Max' passwd 'Maxi'). Depending
    on how you started the server (with or without SSL), enter in the
    location field of the browser, where 'your site name' is the name
    of your site (e.g. www.maxscape.com):

       https://'your site name':2080
     or
       http://'your site name':2080

     Depending on your Apache httpd.conf configuration, you can access
     the MaXscape application server via:

       http://'your site name'

18) Before you connect the server to an unsecure network, change the
    passwords of the preconfigured Maxscape users (other users of this
    distribution do know the preconfigured users and passwords).

    This can be done via the Maxscape administration server surface or
    the Maxscape MaxAdmin shell tool. With the MaxAdmin tool the
    database tables can be created and dumped into ASCII files, located
    under the application servers directory structure. To change the passwords
    edit the 'USERS.sql' file and change the 4'th column of each record
    to the new passwords:

      vi /maxscape/server/WebServer/tables/USERS.sql

        INSERT INTO USERS VALUES ('Max','system',3,'MyOwnPassword', ...
        ...

    After this recreate the USERS table with the Maxscape MaxAdmin
    shell tool:

      MaxAdmin -w WebServer create Table USERS

19) If you have problems, send a message to Max at www.maxscape.com.


7. ORACLE hints
===============

If you do use oracle as your favorite database and you have to execute the
Maxscape oracle database instanciation script for initial oracle setup.
Edit the following two files:

1)  Assign the database type 'oracle' to the shell variable
    project_db_type in the maxscape global profile (/maxscape/etc/profile): 

     vi /maxscape/etc/profile

         [ -z $project_db_type ] && project_db_type=oracle

       also add a line like:

         . /home/oracle/app/oracle/product/'version'/dbs/profile

    to execute the oracle profile (if it exist's-:), to set the
    necessary environment variables for oracle, e.g.:

      export oracle_home=/export/home/oracle/app/oracle/product/'version'
      export path=$oracle_home/bin:$path
      export oracle_sid=www
      export oracle_term=vt100
      export ora_nls32=$oracle_home/ocommon/nls/admin/data
      export ora_nls33=$ora_nls32
      export nls_lang=german_germany.we8iso8859p1
      export oracle_db1=/home/db1
      export oracle_db2=/home/db1
      export oracle_db3=/home/db1
      export oracle_db4=/home/db1

    some oracle installations requires the LD_LIBRARY_PATH
    variable is passed to the apaches fcgi appclass directive via:

      appclass /maxscape/server/myserver/docs/www.fcg 
         -processes 3 
         -listen-queue-depth 5 
         -restart-delay 0 
         -initial-env LD_LIBRARY_PATH=/opt/oracle/app/oracle/product/'version'/lib 
         -initial-env PROJECT_SERVER_NAME=myserver

      (see the httpd.conf file).

2)  Edit the maxscape runtime system configuration file, to set up
    the oracle database user identification and passwords for the
    configured application server:

      vi /maxscape/etc/maxscape.cnf

          <hash>
           <item key="main">
            <hash>
             ...
             <item key="database::product">oracle</item>
            </hash>
           </item>
           ...

3)  After oracle database instanciation start the database and recreate the
    Maxscape administration server tables:

      su - oracle
      dbstart
      exit
      su - maxscape
      MaxAdmin -w WebServer create Tables

4)  Start the apache via it's init script or adapt the Maxscape start
    scrit to oracle.


7. CONCLUSION
==============

Have a lot of fun and thank you for your patience...

Copyright Maxscape (c), all rights reserved.

nextprevioustopbecome a membercontact © Maxscape