docs.roxen.comBack to normal mode
DocsRoxen2.2Administrator ManualInstallation
Copyright © 2004, Roxen Internet Software
Suggestions, comments & compliments
manuals@roxen.com

Software Installation

The software installation installs Pike and Roxen on your system. It is either done through a binary or source package. Binary packages are precompiled for each operating system and are the easiest to install. Source packages are compiled by the user and require a complete development environment. They are for people who want full control over what they install, or a last resort if a binary package fails.

Windows Binary Installation


Installation wizard

The Windows binary relase is distributed as a self-installable package. Just start it and a wizard will guide you through the installation.


Administration interface dialog

The first dialog with actual Roxen specific settings is for creating the administration interface for your server. The settings are Server name, Protocol, Port, Admin user name and Admin password. Server name is the name of the administration interface site.

Protocol is the protocol that will be used to access it. It should normally be https to ensure that the traffic is encrypted. Note that it is also necessary to create a new certificate, since it will use the insecure demo certificate by default.

Admin user name and Admin password are the user name and password who will be used to access the admin interface.


Update client dialog

The next dialog asks whether your Roxen server will connect to the update server at roxen.com automatically or not. If you allow it the builtin update client will fetch information about new software and updates as well as news about Roxen. The information will be displayed in the Admin tab of the administration interface.

If you do not allow this it is still possible to use the update client, it will connect to the update server and fetch information when you tell it to. The disadvantage is that you will not get automatic alerts about new security fixes and other important news.

If you have a Roxen Community user you can let the update client connect with your user name and password, to let it download packages that require authentication. The Roxen Community, http://community.roxen.com/, is a community for Roxen users. The update server is part of Roxen Community.


Install as a service dialog

If you install on Windows NT or Windows 2000 you will also be prompted whether you want to run Roxen as a service or not. If you are installing to run the web server in production you should run it as a service. If you are installing to do development it is better to start it manually from the Start menu.


Last dialog

The last dialog will enable you to start Roxen. If you do so Roxen will be started with the debug log in a console windows.


Roxen console

Unix Binary Installation

The Unix binary release is distributed as a self-installable archive, actually a combination of a sh-script and a tar archive. The result is an executable with its own installation script that guides you through the installation.

During the installation process the install script will create and extract files to a temporary directory. It will create the directory in the current directory. The installation script will tidy up after itself, but if it is not able to it is safe to remove a directory with a temporary sounding name like DtmPf4a2b26/.

To install the binary release, simply run the archive:


sh roxen-2.2.[build]-[os].sh

Then press enter and accept the license text by answering yes.

It will take a while for the script to extract the Pike binary and start the real installation script. When it has finished it will prompt for the location of your installation:


Installation prefix ("roxen" will be added): /usr/local

If you do not enter anything Roxen will be installed in /usr/local/roxen/. Roxen is always installed in a directory called roxen. For automatic updating just enter the same location as the old installation. The old installation will be kept, but make sure the old server is not running. For more information see the Updating chapter.

Now the actual installation of the software will take place. This takes a while and shows nice progress bars. Next the installation script will create an administration interface server. If the installation updates an existing installation it will skip this step.

The script will prompt for the name and URL of the administration interface server, as well as the user name and password for an administraion interface account.

Note!

It is no longer necessary for the administration interface to run under its own port, you could assign it a URL on your normal server, for example http://my-domain/admin/. See the Ports chapter for more information.

The https protocol should be used for the administration interface, otherwise it might be possible to eavesdrop on it. To make it secure it is not enough just to choose a https URL, it is also necessary to create a new certificate, since it will use the insecure demo certificate by default.


   Creating an administration interface server in
   /home/wing/cto/manual/roxen/configurations/.

Server name: Administration Interface
Port URL: http://*:27474/
Administrator user name: administrator
Administrator password:
Administrator password (again):

Are the settings above correct [Y/n]?

The last stage of the installation process asks whether your Roxen server will connect to the update server at roxen.com automatically or not. If you allow it the builtin update client will fetch information about new software and updates as well as news about Roxen. The information will be displayed in the Admin tab of the administration interface.

If you do not allow this it is still possible to use the update client. It will then connect to the update server and fetch information when you tell it to. The disadvantage is that you will not get automatic alerts about new security fixes and other important news.

If you have a Roxen Community user you can let the update client connect with your user name and password, to let it download packages that require authentication. The Roxen Community, http://community.roxen.com/, is a community for Roxen users. The update server is part of Roxen Community.


   Roxen has a built-in update system. If enabled it will periodically
   contact update servers at Roxen Internet Software over the Internet.

Do you want to enable this [Y/n]? Y

   If you have a registered user identity at Roxen Community
   (http://community.roxen.com), you may be able to access additional
   material through the update system.

   Press enter to skip this.

Roxen Community identity (your e-mail): wing@roxen.com
Roxen Community password:
Roxen Community password (again):
Do you want to access the update server through an HTTP proxy [y/N]?

The last question is for users who run their Roxen server behind a firewall. Then it might be necessary for the server to use a proxy like any web browser between a firewall.

With this the installation script has all the information it needs. It will finish the installation and start the Roxen server. Further configuration is done by connecting to the administration interface, the installation script prints the URL. If it is not possible to connect to the administration interface, the debug log file should give clues to what went wrong. It is located at roxen/logs/debug/default.1.


   Administration interface created.

   Administrator user "administrator" created.

   The initial installation is complete. Starting Roxen WebServer,
   please wait.........

   Congratulations! Your webserver has started. You may now proceed with the
   installation from the administration interface using a web browser:

   http://holt:27474/

Unix Source Installation

The Unix source release is distributed as a tar.gz archive. It contains the source code for the Pike interpreter, necessary libraries and the Roxen server itself. The installation will work on any system, but libraries for all supported functionality is not included. Thus libraries for native database support, for image file format support (TIFF, JPEG), TrueType rendering, Java, or GTK/GNOME support are not included.

If you are installing on a Linux or FreeBSD system most libraries will be shipped with the distribution. The commercial Unix system does however usually not ship these libraries, so you will have to install them yourself.

It is necessary to install the external libraries before you install Roxen. If you later find out that some function is lacking because of a missing library you will have to reinstall Roxen, or rather the Pike interpreter. A reinstallation is done in the same way as an installation and does not affect the web sites you have created. The installation script will find the previous installation of Roxen and upgrade rather than overwrite it.

The installation process consists of four steps; configuration, compilation, software installation and Roxen installation.


./configure --prefix=/usr/local
make
make install
cd /usr/local/roxen/server
./create_configinterface

The configuration is done automatically by a script created with GNU autoconf. It finds out about your system and how to compile on it. It will find which libraries are installed and if they can be used. Usually this will be fully automatic but in some cases it might be necessary to manually force the configuration system to find some libraries. Use ./configure --help for a list of configurations options.


./configure --prefix=/usr/local/

The configure script produces a log about what happens. A longer version of the log is also stored as config.log. If the configure script failed to find a certain library that does exist the config.log file will give you valuable clues to why, and what you can do to fix it. Once you have fixed the problem you can run configure again.


holt roxen-2.1.130-src $ ./configure --prefix=/usr/local/
loading cache ./config.cache
checking whether make sets ${MAKE}... (cached) yes
checking for a BSD compatible install... (cached) /usr/local/bin/install -c
configure: warning:  Converted . to /home/wing/cto/manual/roxen-2.1.130-src,
If this does not work, please use an absolute path to the configure script.
creating ./config.status
creating Makefile
configuring in pike/src
running /bin/sh /home/wing/cto/manual/roxen-2.1.130-src/pike/src/configure  --prefix=/usr/local/ --cache-file=../.././config.cache --srcdir=/home/wing/cto/manual/roxen-2.1.130-src/pike/src
loading cache ../.././config.cache
checking for gcc... gcc
checking whether the C compiler (gcc  ) works... yes
Beginning of configure log

After the software is configured, it is time to compile it. This is done by invoking make which will in turn use the necessary compilers, linkers and whatnot. The compilation takes a while and produces another long log of information. Usually all messages can be ignored, but in case of errors they will provide important clues to what went wrong.


make

holt roxen-2.1.130-src $ make
make[1]: Entering directory `/home/wing/cto/manual/roxen-2.1.130-src/pike/src'
Creating lib/.
Creating lib/modules/.
Creating lib/include/.
Creating symlink ./share
Done.
t="$PIKE_PATH_TRANSLATE"; if test "x$t" = "x"; then t=s,x,x,; else :; fi; \
sed -e 's!¤lib_prefix¤!'"`echo \"/home/wing/cto/manual/roxen-2.1.130-src/pike/src/lib\" | sed -e \"$t\"`"'!' </home/wing/cto/manual/roxen-2.1.130-src/pike/lib/master.pike.in \
  | sed -e 's!¤share_prefix¤!'"`echo \"/home/wing/cto/manual/roxen-2.1.130-src/pike/lib\" | sed -e \"$t\"`"'!' >master.pike
Beginning of make log

When the software has been compiled it is time to install it. This is usually done by make install. The make command, that is used to handle the compilation process, is used to handle the installation process as well. The software will be installed in the directory that you specified with the --prefix= argument to configure, by default /usr/local/.

Roxen and Pike will both be installed separately, in their own directories (pike/ and roxen/). A link to the pike binary will also be created in bin/. The roxen directory can later be moved anywhere on your system. However the pike directory cannot be moved. In case you want Pike and Roxen in different places you should set the --prefix= argument to the configure script for Pike, not Roxen.

Upgrading to a newer 2.x release, or reinstalling the same release, is also done with make install. Only the roxen/server/ directory, that contains the actual software, will be affected. No logs, configurations or user data will be touched. After the installation the old version of the software will be moved from roxen/server/ to roxen/server.old/.

The installation also produces a progress log that is mainly interesting in case of errors.


make install

holt roxen-2.1.130-src $ make install
make[1]: Entering directory `/home/wing/cto/manual/roxen-2.1.130-src/pike/src'
make[2]: Entering directory `/home/wing/cto/manual/roxen-2.1.130-src/pike/src/modules'
Making CommonLog
make[3]: Entering directory `/home/wing/cto/manual/roxen-2.1.130-src/pike/src/modules/CommonLog'
make[3]: Leaving directory `/home/wing/cto/manual/roxen-2.1.130-src/pike/src/modules/CommonLog'
Making Gdbm
make[3]: Entering directory `/home/wing/cto/manual/roxen-2.1.130-src/pike/src/modules/Gdbm'
make[3]: Leaving directory `/home/wing/cto/manual/roxen-2.1.130-src/pike/src/modules/Gdbm'
Beginning of make install log

The next step is to create an administration interface server. If you are upgrading or reinstalling you do of course not need to, your old configuration will do. This is done by invoking the create_configinterface script located in the roxen/server/ directory. If is the same script that is used by the binary installation, so we won't describe it in detail again.


cd /usr/local/roxen/server/
./create_configinterface

   Creating an administration interface server in
   /usr/local/manual/roxen/configurations/.

Server name: Administration Interface
Port URL: http://*:22424/
Administrator user name: administrator
Administrator password:
Administrator password (again):

Are the settings above correct [Y/n]?

   Roxen has a built-in update system. If enabled it will periodically
   contact update servers at Roxen Internet Software over the Internet.

Do you want to enable this [Y/n]?

   If you have a registered user identity at Roxen Community
   (http://community.roxen.com), you may be able to access additional
   material through the update system.

   Press enter to skip this.

Roxen Community identity (your e-mail): wing@roxen.com
Roxen Community password:
Roxen Community password (again):
Do you want to access the update server through an HTTP proxy [y/N]?

   Administration interface created.

   Administrator user "administrator" created.

The last step of the software installation is to start the server and connect to the administration interface. This is done by invokning the start script in the roxen/server/ directory. The progress of the server can be seen in the debug log, roxen/logs/debug/default.1


cd /usr/local/roxen/server/
./start

 7:54:46  : ----------------------------------------------------------
 0m 0.0s  : Pike v7.0 release 230, Roxen WebServer 2.1.130
          : Loading pike modules ... Done [855.0ms]
          : Loading roxen ... Done [7884.8ms]
          : Loading font handlers ...
          :     Builtin fonts (scalable)
 7:54:55  :     Compact image file font (bitmap)
 0m 9.5s  :     Image directory fonts (bitmap)
          :     Image TAR-file fonts (bitmap)
          :     Compatibility bitmap fonts (bitmap)
          :     TTF fonts (scalable)
          : Done [516.5ms]
 7:54:56  : Adding languages ... Done [45.05ms]
 0m 9.7s  : Initiating argument cache ... Done [101.31ms]
          :
          : Enabling the configuration Administration Interface ...
          : Registered http://*:27474/ for Administration Interface
          : Enabled Administration Interface in 412.1ms
 7:54:56  : Starting 5 threads to handle requests.
 0m10.2s  : -- Total boot time 10.2 seconds ---------------------------
          :
          : ** 2000-09-20 07:54   pid: 15469   ppid: 15460   uid: wing
Beginning of debug log