The instructions below will guide an administrator through an install of the WebGUI Runtime Environment (WRE) v0.8.3 binary build from scratch. If a binary build is not available for your platform, you'll need to build the WRE from source. For more information you can refer to the WRE-Building wiki topic.
NOTE: This wiki article is an expanded version of the install.txt file that is included in all WRE binaries and source downloads.
This article is for people who are installing v0.8.3 from scratch. If you are running an earlier version of WRE, you should check out the "Migration to WREv0.8" article as well.
Platform specific information is available at the end of this document for:
- Red Hat Linux
- Microsoft Windows XP on X86
- Ubuntu 7.04 on AMD64
- Mac OS X
PRIOR TO INSTALLING
The WRE works best on a Linux-based operating system.
As of January 2008, the officially supported platforms for the binary build of the WRE are:
Debian Linux
Red Hat Enterprise Linux 3, 4, and 5
Mac OSX 10.5 (intel)
Mac OSX 10.4 (PPC)
FreeBSD 6.2
Ubuntu 6 Server
SuSE Linux Enterprise Server (SLES) 10 SP1
Windows XP, Windows Server 2003
The RHEL versions seem to work fine on the associated CentOS releases (atleast v4 does, as that's what Baylink has installed, and under OpenVZ,no less). The SLES 10 version at least installs on OpenSUSE 10.2, and seems to run ok, though it has not yet been extensively tested.
If you have any older version of WRE installed, you cannot upgrade it directly to 0.8.x.You will have to export your sites, move the old release aside, and install the new release from scratch, and finally reimport your sites.
Understand: You can(or at least, you likely will be able to) install using WRE 0.8 the same version of WebGUI that you had installed under an earlier version(though it's not yet clear how old a version will run)... it's just that you'll have to dump and reload your sites; you can't just pick the WebGUI install up and move it to the new WRE.
(It appears those 2 paragraphs may slightly overstate the difficulty; please keep take a look at the Migration to WRE 0.8 article for more.)
That applies to upgrading WRE, it's much easier to upgrade the WebGUI install running atop a particular WRE instance.
And, of course, everything on this page is subject to change without notice.
INSTALLING
1. Unpack the archive.
mkdir /data
cd /data
tar xvfz /path/to/wre-x.x.x-osname.tar.gz
Ifnecessary, you can physically locate the directory in which you unpacksomewhere else (Baylink puts his in /appl/wre, since /appl is the "bigfilesystem on another drive" on his machines for hysterical raisins),and symlink it; this appears to work just fine, though no guaranteesare expressed or implied:
mkdir /appl/wre
cd /appl/wre
tar xvfz $TARBALL
cd /
ln -s /appl/wre data
2. Add a "webgui" user to the system
Note that you can name this
user whatever you want, but we recommend "webgui". On most systems
you run a command similar to the following as the root user:
adduser -s /sbin/nologin webgui
- or -
useradd -s /sbin/nologin webgui
- or -
adduser --system --no-create-home webgui (Ubuntu)
NOTE:If you're just using the WRE for development on your machine, feel freeto just use your own user account rather than creating a new one.
ANOTHERNOTE: If you've su'd to root to do the install, note that useradd andfriends are often in /sbin or /usr/sbin, and su will usually not addthose to your PATH, so you'll have to do it yourself.
3. Kill system Apache and MySQL
If you have an existing Apache or MySQL running please shut them down now.
On most systems you can shut them down hard by running commands like this:
killall mysqld
killall httpd
Ifthey're being started by the service controller system (/etc/init.d,etc), you'll want to make sure they're turned off there as well (withchkconfig, usually).
4. /etc/my.cnf
If you have a MySQL config file at /etc/my.cnf please remove or rename it so that it doesn't interfere with the WRE MySQL.
mv /etc/my.cnf /etc/my.cnf.old
As of WRE 0.8.0, the web install console will actually warn you if there's a config file at /etc/my.cnf.
NOTE:if you have a reason to run a 'system' MySQL in addition to the oneinside the WRE, this is the wrong answer, but you're expected to knowhow to deal with this if you need to do that.
5. Set up DNS
Createyour DNS entries (or add entries to /etc/hosts) for the sites you willbe using, including the AWStats site. The WebGUI machine must be ableto locally resolve, somehow, each domain name you're going to set up asite on.
Sometimes, if you're going to create a site on a WebGUImachine to replace one that already exists, you'll need to put thatsitename in the machine's /etc/hosts, and in the hosts file of the PC'syou'll be doing the setup from, since you don't want to modify thepublic DNS until the site is ready. Don't forget to take them back outonce you cut over.
6. WRE Console
Run the WRE Consolewhich you can use to configure WebGUI. The WRE Console is a newweb-based configuration interface which lets you control the variousWebGUI support services (mod_proxy & mod_perl apache servers,spectre and the MySQL database), create and delete WG sites on theserver, and modify configuration files.
cd /data/wre/sbin
. setenvironment.sh
wreconsole.pl
NOTE:If you get an error message about 'socket macro SO_REUSEPORT' beingundefined, comment out line 41 of wreconsole.pl with your favoriteeditor, or whichever line looks like this:
ReusePort => 1,
atthe beginning of the 'server daemon' section of that file. You cancomment it out by putting a '#' at the beginning of the line. Thisproblem appears to have been correctly fixed in the production release,and you shouldn't have to deal with it.
NOTE: If you are not an administrator on this machine you should start the WRE console with sudo like this:
sudo ./wreconsole.pl
TheWRE Console will be available by web browser at port 60834 while thisscript is running, and any diagnostic information it produces will comeout on the text console from which you started the perl script. Whenyou kill the script, or log out of the terminal session, the Consolewill disappear.
NOTE that the console is not currently secured, so you don't want to leave it running when you're not using it.
NOTE: You should probably add the following command to your profile so it executes every time you log in:
. /data/wre/sbin/setenvironment.sh
place in your .bashrc file, normally /home/USERNAME/.bashrc ( ubuntu )
for root user /root/.bashrc ( ubuntu)
Thiswill ensure that if, for example, you need to use perl to runsomething, you get the WRE version of perl, not some other one whichmight be installed in your OS.
7. Go to the Console
Use your favorite web browser to visit the WRE Console setup page:
http://localhost:60834/ - or -
http://www.example.com:60834/
NOTE: You may have to open a firewall port to access this.
ThatURL originally ended in /setup, and leaving it off would cause youproblems, but the text-console no longer tells you to add it on, andleaving it off seems to work ok.
8. Finish configuration
Follow the on screen instructions to complete the configuration.
NOTE:Safari is not capable of displaying a page as it's being downloaded soit is not the best browser you can use for the setup process, which isa realtime process. Safari will work in most cases, but it is notideal. Plain Black recommends Firefox instead.
a. Operating system username
Enterthe Linux(/Windows) username you created above, or accept the default'webgui'. If you want to configure this entire WRE install fordevelopment, choose Yes; if you don't know what that means or why you'dwant to, choose No. Click Next.
b. Apache ports
Youalmost always want to accept the default ports for mod_proxy andmod_perl servers here; if you don't, you know why already. Click Next.
c. MySQL setup
The next screen prompts you for the hostname, port number, and admin user info for the WRE's MySQL database engine.
The host will always be 'localhost', the default, unless you're running a DBMS on a different machine that you want to use.
Theport number should also be left default, unless needed, and you'll knowif it's needed. (Are you getting tired of hearing that yet? :-)
The username and password are the ones that will be createdin the new database for you as the admin user. Unix people willprobably want to leave that as root; Windows people might want tochange it to administrator. Set a decent password. (If you'rewondering what you're up against, read this Bruce Schneier article. I usually recommend 2 uncommon but memorable words separated by a 2 digit number. mambo69giraffe, for example.)
You'lloften be told never to write down passwords. In general, that's easiersaid than done. If an attacker gains physical access to your machine,your login passwords don't mean much, anyway, so write them down in afolder, and twine it to your CPU. Then lock the room with a goodlock. (I am not a lawyer; if that advice gets you in trouble, don'tblame me :-)
c. spectreSubnets
The next page prompts youfor a variable which is internally called spectreSubnets. This tellsWebGUI which IP addresses it can expect the SPECTRE job runner toconnect from. On a single machine setup (the default) that will be allthe physical IP interface addresses, specified in CIDR notation; the default should be ok.
d. Ready To Install
WREis now, as it notes, ready to configure itself, and download andinstall WebGUI. If you want WRE to install the latest version ofWebGUI, press the Automated button, if you want to install a specificversion yourself, do so now, from another text console window (don'tinterrupt the one that wreconsole.pl is running in; you still need it),and then press the Manual button.
If you choose Automatic,wreconsole will download and install the latest stable version ofWebGUI; if you want to install a beta version you'll have to chooseManual mode.
(Baylink had occasion to have the wreconsole freezeat the beginning of this step, never leaving the browser screen wherespectreSubnets was prompted for.
I interrupted wreconsole.pl inmy terminal window, restarted it, and refreshed the browser window; itautomagically proceeded to ask me about the install mode. Kudos, JT. Multistage installs that store the answers somewhere useful as they goare A Good Thing.)
e. Configuration runs
While theactual configuration runs, you'll see progressive status messages inyour web browser, and slightly more detailed ones in the text consolewindow in which you left wreconsole.pl running -- most of which youshould ignore, especially ones which tell you to do things to MySQL;the script is doing those things for you.
After a minute or 5, if you scroll the browser window down, you'll see "Configuration Complete".
Youcan then click on the link at the bottom of the page, and you'll betaken back to the same URL you started with... but now the wreconsoleknows it's installed, and it lets you manage the server, instead.
Thisis the point in this process which you can and will return to manytimes over the life of your server. When you launch the wreconsole asexplained in step 6, above, in the future, this will be where it takesyou.
9. Add a site
Go to the "Sites" tab (actually, you should already be there, the first time through) and add your first web site.
a. Add Site
Click'Add Site'. Fill in the MySQL admin password you set earlier, and thefull public domain name of the site you're setting up. If you'reCNAMEing public names to a physical server name, enter the alias here(www.baylink.com, instead of panther.baylink.com).
You needn'tset the site username and password if you won't be interacting with thesite from outside WG (and you really shouldn't :-); they'll begenerated for you.
I don't know what the custom variables actually do, but set them here if you need to.
Finally, if you haven't already, make sure that site name that you entered above can be resolved by the server itself, either by putting it in the server's /etc/hosts file, or by adding it to the appropriate public DNS zone.
Then click 'Create Site'.
Ifyou get an error that sounds like 'you didn't type the password right,silly', you probably didn't. Click Back, fill it in again, and clickthe 'Adding...' button to try again.
Otherwise, we'll
b. Edit configs, if necessary
Clickthe 'Edit' button for the site you've just created (if this is not yourfirst site, you'll see them all listed here, and you can make certainchanges to any site).
Edit any config files you feel the needto. All the various config files are somewhat sensitive to syntax, sotry not to inadvertantly break quoting and such if you need to edit. If you're using custom assets or wobjects, for example, you'll need toedit the site domain.conf file.
If you have a small site, andaren't ready to deal with the extra power and complexity of versioningquite yet, look for enableSaveAndCommit in the domain.conf, and turn iton. (?)
10. (Re-)Start Services
Go to the "Services"tab and start mod_perl, mod_proxy, and S.P.E.C.T.R.E. MySQL should berunning already, and you needn't restart it. Note that 0.8.0 listsmod_proxy first; you should start mod_perl first anyway on your initalsetup, or you'll get a spurious error message; this has been fixed forWRE 0.8.1.
You will likely find it useful to have an extraterminal window running (I use PuTTY, maximized to the entire size ofmy screen), running
$ watch -d ps -axf
So that you can see that things have started.
11. Visit your new web site!
You'll need to answer a few questions to set up each new website you create in WebGUI.
Opena new window or tab in your web browser, and point it to the homepageof your newly created site. As noted above, if you have not added thatsite's IP address to the Public DNS yet, you'll need to make sure thename and address are in the hosts file on your workstation.
You'llnow be looking at the Admin Account setup page of a newly createdWebGUI website. As we noted above, this is not secured, so get thisfirst step done quickly.
a. Admin username and password
Thesedefault to the Plain Black defaults of "admin" and "123qwe" (type that,and you'll understand why -- unless you like Dvorak keyboards :-)
b. Admin email address
I think this is where the system sends email that's destined for the administrator (CHECKME)
Click the save button to go to the second page, and fill in the
c. Company information settings
Companyname, email, and URL. Should you find you have to set a site up morethan once (this sometimes happens with WebGUI and new installers :-),remember that these fields are probably remembered in your browser'spulldown menus, which can save you some typing.
12. Cron Jobs
Addthe following cron jobs to your server's cron tab as suggested by theConsole. If you had an older WRE installed on the machine, they'reprobably there, though possibly with different run times.
Whichcrontab file you should put them in depends to some extent on the OSyou're on. On Ubuntu, you can put them in /etc/crontab. On RedHatderived OS's, they can go in root's crontab (crontab -e -u root)
- 0 0 * * * /data/wre/sbin/logrotate.pl
- */3 * * * * /data/wre/sbin/wremonitor.pl
- 0 2 * * * /data/wre/sbin/backup.pl
If you are using the demo system then add this:
- 0 0 * * * /data/wre/sbin/democleanup.pl
PLATFORM SPECIFIC NOTES
Red Hat Linux
This note applies to all linux' that use chkconfig to setup services. These
include RHEL, Fedora, Mandrake, SuSE, CentOS, and others. You can set up the
WRE to start automatically at system boot by running the following commands
after the WRE is installed:
- ln -s /data/wre/sbin/services/redhat/webgui /etc/init.d/webgui
- chkconfig --add webgui
- chkconfig webgui on
Mac OS X
There is no command line user add script on Mac OSX. Therefore you can either
use the graphical "Accounts" manager in "System Preferences", or the really
horrible "netinfo" command line utility. Alternatively, you can also download
some free user utilities from this site:
http://www.osxgnu.org/software/pkgdetail.html?project_id=231#4095
Once you've installed the WRE you'll need to edit /data/wre/etc/modperl.conf
and comment out the following lines, which should be around line number 155:
#PerlRequire /data/wre/etc/modperl.pl
#PerlCleanupHandler Apache2::SizeLimit
The reason is that Apache2::SizeLimit is not supported on Darwin based
systems.
Ubuntu 7.04 on AMD64
TheUbuntu package did not work for me on this platform. I was gettingerrors trying to run perl and mysql. So, I downloaded the source filesto install the old-fashioned way. See WRE-Building for the steps and apatch for build.sh.
Windows XP on x86
Alternate Installation Guide
See the Install PDF by SIgnal Mountain available at www.signalmountain.co.uk/WebGui.html
Troubleshooting
Make sure you unpack into C:\data. (This is described in the Linux instructions, but easy to miss with a Windows hat on.)
There are some useful documents in C:\data\wre\docs, including the following included in install.txt:
- Touse the .pl commands (like wreconsole.pl) you need to double-clickon the "Command Prompt.bat" icon in your /data/wre/sbin folder, andthen run the commands by prefixing them with "perl ", like this:
perl wreconsole.pl
Itdid not install properly when I changed the MySQL default username -could not connect properly during the site configuration phase. Therefore accept the defaults for this (and everything else.)
Beforeyou install the WRE, make sure that you have disabled IIS or during theinstall choose a port other than 80 for mod_proxy to run on.
WebGUI user does not matter when installing to Windows. All WRE services are run under a System account.
In windows you can find the hosts file in c:\windows\system32\drivers\etc\ so typically you put this into a command prompt:
edit c:\windows\system32\drivers\etc\hosts
I received this error when trying to run Apache from wreconsole.pl during the install:
The application has failed to start because MSVCR71.dll was not found.
0.8.0-windows-ia32.zipis packaged with MSVCR70.dll. You will need to update to MSVCR71.dlland MSVCP71.dll in C:\data\wre\prereqs and run wre-console.pl again.
Keywords: 0.8.0 wre 0.8.1 0.8.3 install
