BlueShoes Installation: get blueshoes running

get blueshoes running

Andrej Arn Sam Blume blueshoes

version:

1.3, updated  2003-06-03

requirements:

apache (1.3.x or 2) and php >= 4.2 are already installed on your system.

you have linux, windows or whatever.

understanding: how to configure apache, add a dns or hosts entry

pre-notes:

it is wise to create similar environments everywhere you run your sites. dev machines, live servers etc. that will make your life easier!

get the code

using the distributed package

using cvs

you already have a web site, or want to create a new one. lets update the apache configuration.

hosts

lets say you own blueshoes.org and want to develop that site on your workstation. to make things easier, i recommend adding a hosts entry. you can do that in your dns server, or on windows you can just edit your hosts file:

its called hosts with no file extension and can be found somewhere in the windows folder. winnt and win2k should have it in c:/winnt/system32/drivers/etc/.

add this line:

127.0.0.1 dev.www.blueshoes.org

save the file, and the new host should work. you may want to use your real ip address instead of 127.0.0.1.

if you have a real domain pointed to your box, thats ok too :-)

if you dont want to do all that, youll have to use your ip address to access the dev site.

create dirs for the website

now we need to put the website somewhere.

as example, we use the dir /web/ to put all the sites in. for the blueshoes site, we create a subdir, like

/web/www.blueshoes.org/

so if you have other domains, they look like:

/web/www.othersite.com/

now we create subdirs:

/web/www.blueshoes.org/online/

/web/www.blueshoes.org/logs/

/web/www.blueshoes.org/data/

/web/www.blueshoes.org/whatever/

your document root (the directory that gets hit when one enters your domain name into his browser) is online, nothing else. so you can still have things that belong to this site, but are not accessible from the web. (i wish all isps would set up the hosting accounts like this)

the online dir could also be named webroot, web, www, htdocs or whatever. we call it online by convention. if you go with that, you need a bit less manual configuration.

note: even if we have created a hosts entry named dev.www.blueshoes.org and not just www.blueshoes.org i highly recommend to name your directory like the final domain name. because when you create that configuration on the web server, its easier if the path matches.

configure apache: httpd.conf

lets add (or update) the site entry in your apache configuration. that can be in the httpd.conf, but maybe you have your sites configured in a file named srm.conf.

feel free to change these options, like indexes etc. or to restrict the access from the outside world.

note: if youre on windows, you may have to specify the path for the aliases like

c:/usr/local/lib/php/blueshoes/toolbox, with the drive letter in front. there was a bug in apache 1.3.something that required this.

on a live box you may want to disable the first group of aliases for security reasons.

the 2^nd part (alias for real usage) is absolutely needed. using this, youll be able to hit files directly, eg https://www.blueshoes.org/_bsImages/spacer.gif

if you are not allowed to edit the apache configuration, and cannot achieve the same results with htaccess files (does this work?), then you need to *copy* the directories into subdirs in your doc root, example:

copy /usr/local/lib/php/blueshoes/images to /web/www.blueshoes.org/online/_bsImages.

this is no fun, but works.

Make sure that $_SERVER['DOCUMENT_ROOT'] ends with a slash. I believe that when your DocumentRoot definition in the VirtualHost directive has one, you are fine.

configure blueshoes for your site; global.conf.php

grab the file global.conf.php-dist from the root dir of your unpacked blueshoes and put it into the /web/www.blueshoes.org/ directory, so one above the webroot. if youre on a server where you cannot break out of the webroot, put the file into your webroot. that sucks, but happens and with some hacks it can be supported.

rename it to global.conf.php. open it, we need to do some changes.

as you can see its a php file. no xml or ini file to parse, so its fast and simple.

if you want to use sessions, make sure the path specified in

$APP['sess']['path'] exists. by default that would be /web/www.blueshoes.org/session/.

also set $sessionType to something, namely simple or file.

if you want to use an automatic browser check as blueshoes.org does it, activate $APP['browscap']['use'].

set the vars $APP['emailWebmaster'] and $APP['emailSysop'].

update the array $APP['usedLanguages'], specify the languages used on your site.

find the key $APP['db'] and update that array. later down the file you can open up the default db connection. the advantage of doing it in the config file is that you dont have to do it in your code anymore.

it is wise to create a database for each website. i recommend setting

$APP['db']['main']['name'] = siteblueshoes; (or so, use the name of your site).

then create such a db:

create database siteblueshoes;

your db user needs full access to this db, and needs at least read access to the BsKb database (if you use the knowledge base).

remember: if you add a mysql db user, dont forget to execute flush privileges.

kb

the kb is distributed in packages on their own, and made available to registered developers and customers only. they include sql files you can import directly. theyre made for mysql, but it shouldnt be hard to use them for any other rdbms.

now restart your apache, and blueshoes should be running.

having problems? read this file again. then go to https://developer.blueshoes.org/forum/

mod_gzip

If cpu isnt so much an issue on your server, and you want to save bandwidth and speed up your site, i recommend you install apache mod_gzip.

it will compress the content you specify (php output, js files, static html files, whatever). browsers since 1998 are capable of reading compressed input, others are fed with uncompressed nourishment.

The url for this used to be:

https://www.remotecommunications.com/apache/mod_gzip/

But they seem to have lost the domain and a domain dealer got it. So use Google.

php-accelerator

also consider installing a php cache. you may want to read the file

https://www.blueshoes.org/articles/Bs_Speed_Matters.article.pdf