The instructions below will guide an administrator through an install of a WRE 0.8.1 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.
Please 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 0.8.1 from scratch. If you are running a WebGUI site(s) on an earlier version of WRE, you should check out the Migration to WRE0.8.1 article as well.
And finally, read everything before doing anything (as they used to say in school, though we will not put an instruction at the bottom that says "put your name at the top of the answer sheet and stop." :-), especially the Platform Specific Notes at the end -- especially if you're running on Windows.
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
The RHEL versions seem to work fine on the associated CentOS releases (at least 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.0.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 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
If necessary, you can physically locate the directory in which you unpack somewhere 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 guarantees are 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)
- or -
useradd -r webgui (debian etch)
NOTE:If you're just using the WRE for development on your machine, feel free to 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 and friends are often in /sbin or /usr/sbin, and su will usually not add those 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
If they'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 (with chkconfig, 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 one inside the WRE, this is the wrong answer, but you're expected to know how 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 will be using, including the AWStats site. The WebGUI machine must be able to locally resolve, somehow, each domain name you're going to set up a site on.
Sometimes, if you're going to create a site on a WebGUI machine to replace one that already exists, you'll need to put that sitename in the machine's /etc/hosts, and in the hosts file of the PC's you'll be doing the setup from, since you don't want to modify the public DNS until the site is ready. Don't forget to take them back out once you cut over.
6. WRE Console
Run the WRE Console which you can use to configure WebGUI. The WRE Console is a new web-based configuration interface which lets you control the various WebGUI support services (mod_proxy & mod_perl apache servers, spectre and the MySQL database), create and delete WG sites on the server, and modify configuration files.
cd /data/wre/sbin
. setenvironment.sh
wreconsole.pl
NOTE:If you get an error message about 'socket macro SO_REUSEPORT' being undefined, comment out line 41 of wreconsole.pl with your favorite editor, or whichever line looks like this:
ReusePort => 1,
at the beginning of the 'server daemon' section of that file. You can comment it out by putting a '#' at the beginning of the line. This problem 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
The WRE Console will be available by web browser at port 60834 while this script is running, and any diagnostic information it produces will come out on the text console from which you started the perl script. When you kill the script, or log out of the terminal session, the Console will 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
This will ensure that if, for example, you need to use perl to run something, you get the WRE version of perl, not some other one which might 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.
That URL originally ended in /setup, and leaving it off would cause you problems, but the text-console no longer tells you to add it on, and leaving 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 so it is not the best browser you can use for the setup process, which is a realtime process. Safari will work in most cases, but it is not ideal. Plain Black recommends Firefox instead.
a. Operating system username
Enter the Linux(/Windows) username you created above, or accept the default 'webgui'. If you want to configure this entire WRE install for development, choose Yes; if you don't know what that means or why you'd want to, choose No. Click Next.
b. Apache ports
You almost always want to accept the default ports for mod_proxy and mod_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.
The port number should also be left default, unless needed, and you'll know if it's needed. (Are you getting tired of hearing that yet? :-)
The username and password are the ones that will be created in the new database for you as the admin user. Unix people will probably want to leave that as root; Windows people might want to change it to administrator. Set a decent password. (If you're wondering 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'll often be told never to write down passwords. In general, that's easier said than done. If an attacker gains physical access to your machine,your login passwords don't mean much, anyway, so write them down in a folder, 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't blame me :-)
c. spectreSubnets
The next page prompts you for a variable which is internally called spectreSubnets. This tells WebGUI which IP addresses it can expect the SPECTRE job runner to connect from. On a single machine setup (the default) that will be all the physical IP interface addresses, specified in CIDR notation; the default should be ok.
d. Ready To Install
WRE is now, as it notes, ready to configure itself, and download and install WebGUI. If you want WRE to install the latest version of WebGUI, press the Automated button, if you want to install a specific version yourself, do so now, from another text console window (don't interrupt 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 of WebGUI; if you want to install a beta version you'll have to choose Manual mode.
(Baylink had occasion to have the wreconsole freeze at the beginning of this step, never leaving the browser screen where spectreSubnets was prompted for.
I interrupted wreconsole.pl in my terminal window, restarted it, and refreshed the browser window; it automagically proceeded to ask me about the install mode. Kudos, JT. Multistage installs that store the answers somewhere useful as they are A Good Thing.)
e. Configuration runs
While the actual configuration runs, you'll see progressive status messages in your web browser, and slightly more detailed ones in the text console window in which you left wreconsole.pl running -- most of which you should 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".
You can then click on the link at the bottom of the page, and you'll be taken back to the same URL you started with... but now the wreconsole knows it's installed, and it lets you manage the server, instead.
This is the point in this process which you can and will return to many times over the life of your server. When you launch the wreconsole as explained 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 the full public domain name of the site you're setting up. If you're CNAMEing public names to a physical server name, enter the alias here (www.baylink.com, instead of panther.baylink.com).
You needn't set the site username and password if you won't be interacting with the site from outside WG (and you really shouldn't :-); they'll be generated 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'.
If you 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 click the 'Adding...' button to try again.
Otherwise, we'll
b. Edit configs, if necessary
Click the '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 certain changes to any site).
Edit any config files you feel the need to. All the various config files are somewhat sensitive to syntax, so try 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 to edit the site domain.conf file.
If you have a small site and aren't ready to deal with the extra power and complexity of versioning quite yet, look for enableSaveAndCommit in the domain.conf, and turn it on. (?)
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 be running already, and you needn't restart it. Note that 0.8.0 listsmod_proxy first; you should start mod_perl first anyway on your initial setup, or you'll get a spurious error message; this has been fixed for WRE 0.8.1.
You will likely find it useful to have an extra terminal window running (I use PuTTY, maximized to the entire size of my 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.
Open a new window or tab in your web browser, and point it to the homepage of your newly created site. As noted above, if you have not added that site's IP address to the Public DNS yet, you'll need to make sure the name and address are in the hosts file on your workstation.
You'll now be looking at the Admin Account setup page of a newly created WebGUI website. As we noted above, this is not secured, so get this first step done quickly.
a. Admin username and password
These default 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 more than once (this sometimes happens with WebGUI and new installers :-),remember that these fields are probably remembered in your browser's pulldown menus, which can save you some typing.
12. Cron Jobs
Add the following cron jobs to your server's cron tab as suggested by the Console. If you had an older WRE installed on the machine, they're probably there, though possibly with different run times.
Which crontab file you should put them in depends to some extent on the OS you're on. On Ubuntu, you can put them in /etc/crontab. On RedHat derived 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
The Ubuntu package did not work for me on this platform. I was getting errors trying to run perl and mysql. So, I downloaded the source files to install the old-fashioned way. See WRE-Building for the steps and apatch for build.sh.
OpenBSD 4.2
By default, Apache will not listen on both 127.0.0.1:80 and ::1:80. To change this, you must alter your Listen line in /data/wre/etc/modproxy.conf and /data/wre/etc/modperl.conf to look like so:
Listen [::]:80Listen 0.0.0.0:80
Substitute 8081 for 80 when editing modperl.conf
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:
- To use the .pl commands (like wreconsole.pl) you need to double-click on the "Command Prompt.bat" icon in your /data/wre/sbin folder, and then run the commands by prefixing them with "perl ", like this:
perl wreconsole.pl
It did 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.)
Before you install the WRE, make sure that you have disabled IIS or during the install 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: wre install
