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.