Installing WebCalendar using cpanel
From WebCalendar Wiki
Contents |
[edit] For Beginners
If you're a beginner, you probably don't realize how easy you have it - this install wizard is a HUGE time-saver. Why, back in the day, we had to walk uphill both ways to get this done. :D
If you're an expert, you probably don't realize what the things that beginners don't know are, because you aren't likely to stop and think about something you've known for years.
I find myself in the middle ground, so I hope to fill a need here. Enough with the intro.
[edit] Before you start
First, you need to realize that installing software on a server is not like installing software on Windows. A deeper level of understanding is needed. Either that or very detailed instructions, as I am providing here.
Secondly, much confusion can result if the instructions you are reading don't match your circumstances. I don't know enough to address anything but my own circumstances, but it appears that they are pretty much mainstream, so I hope this helps a lot of people.
This HowTo is for people who are managing their own website using cpanel; those who do not have access to the actual server their pages are on except by FTP (File Transfer Protocol) and cpanel. It assumes that your web hosting company has installed php 4.1.0 or newer as well as MySQL. It assumes your browser is Microsoft Internet Explorer 6 or newer. The differences with other browsers should be minimal, but I don't know enough to say for sure (others should of course feel free to edit here, or anywhere for that matter). It assumes that your web hosting company is willing and able to do a couple small things if needed (this is probably not going to come up) to provide the environment needed to make this wonderful Calendar package work. Finally, it assumes that you know how to use your FTP Client.
[edit] Start Here
Let's take this from the absolute beginning. I'll assume that the only step you've taken is that you know you want WebCalendar on your website, and that you've decided on 1.1.1 even if it is not 100% bug-free. I'll assume that you know how to login to your cpanel, and that you know how to upload files using an FTP client. I'll try to assume nothing else from here on.
[edit] Download the Package
Go to the WebCalendar Development site, which is the main project page provided by the good folks at Source Forge. Go ahead and click on the 'Download WebCalendar' box, taking you to the download list. You want the WebCalendar-devel-1.1.1.zip file - don't even try the files ending in '7z' or 'tar.gz', those are for Unix guys and we're Windows heathens.
So, go ahead and click on WebCalendar-devel-1.1.1.zip which takes you to a page listing mirror sites which will supply the package you've just selected. Pick one and click on the 'download' box. In a perfect world, your download will start. On my Windows system, I get a yellow bar at the top of the page informing me that IE is blocking the download. OK, fine, click on the yellow bar and select 'Download File' - this should bring up a dialog box asking if you want to open or save. Select save, and then choose a folder to store it in, and don't forget where that is.
[edit] Unzip the Package
OK, now use Windows to open the folder that you saved the file in. Find the folder you just downloaded and right-click it and select 'Extract All', taking you into the Extraction Wizard. Click 'next' twice to extract (unzip) the package. It is critical that the unzip step preserves the folder structure, on my machine this is automatic. Your unzipped folder should be (automatically) named 'WebCalendar-1.1.1' and under that folder you should find the following folders: 'docs', 'images', 'includes', 'install', 'tests', 'themes', 'tools', translations', 'ws'. There should also be a long list of php files alongside all those folders.
So that's a little download and unzip lesson. Maybe you already knew all that, but hey maybe not, this is for raw beginners, OK? :D
You've now got the package on your computer so now we need to get it on your webhost's computer and make it work.
[edit] Upload the Package
I am assuming you know how to use your FTP client. Myself, I use SmartFTP, and I would hope that whatever you're using works just as well, and that the following makes sense for whatever FTP client you're using.
Get connected to your website and make 'public_html' your current folder. We are going to upload all these files. Note that you want to use 'Binary Transfer Mode' (NOT 'ASCII Mode') for all this.
Here's the important part: you need to make absolutely sure that when you get done uploading this whole thing that the folders are all arranged exactly as you see them in the 'WebCalendar-1.1.1' folder you just created by unzipping, and that **all** the files are there where they should be. One way to do this is to upload the entire unzipped folder into 'public_html' all at once. The trouble with that is the FTP transfer will almost never make it thru that entire huge upload without crapping out at some point. What I recommend is to create a folder named 'WebCalendar-1.1.1' under 'public_html' and then drag each of the folders listed above into that folder one at a time. Monitor the FTP transfer and verify that ALL the files and folders get completely uploaded. Don't forget to upload the long list of files directly under the top 'WebCalendar-1.1.1' folder.
OK, all verified? Good, now we are getting somewhere!
[edit] Get the reference material
Now, before we plunge ahead, let's RTFM (Read The F-ing Manual), shall we?
To do that, go to the local unzipped 'WebCalendar-1.1.1' folder and open the 'docs' folder. Open the 'WebCalendar-SysAdmin.html' file in your IE browser. This is a great document, but they had to write it for all possible users, and we Windows/IE bums are easily confused, so that's basically why I am writing this HowTo. From here on, this HowTo is a guide to this System Admin Guide, for those of us working via cpanel and FTP.
The 'System Requirements' section is basically information for your web host.
The 'File Unpacking' section covers what we just did by unzipping and uploading. Note that the 'WebCalendar-1.1.1' folder can be renamed. When this is all said and done, your Web Calendar will be accessed by folks pointing their browser to 'www. mydomain .com/WebCalendar-1.1.1' if you don't rename it. I recommend you rename it to 'WebCal', so that browsers will go to 'www. mydomain .com/WebCal' instead. No big deal either way, but now is the time if you want the shorter URL.
The 'Application Installation' is where we get down to business.
But first there are some things you should do so that you sail right thru the 4-step wizard. Two little things and one big thing.
The 'includes' folder needs to have a change made to its permissions. Are you familiar with CHMOD? Of course not, you're a beginner! CHMOD is a UNIX command to change the permissions (read / write / execute) to a file or folder. The 'includes' folder is set to a value of 755 by default but you need to change it to a value of 777. I can do this in SmartFTP by selecting the folder in the remote browser window and clicking the 'commands' menu where I select 'Properties / CHMOD" from near the bottom of that menu list. I simply enter 777 in the Permissions box, click OK and I'm done. If your FTP client doesn't let you do the same thing, you can CHMOD using the File Manager in your cpanel. (I hate cpanel's file manager, but it can serve as a bailout option for stuff like this.)
The wizard is started by pointing your browser to www.mydomain .com/WebCal/install/index.php (assuming you renamed the top level folder to 'WebCal' as per above). If we were ready to go - and we are not - we would start the wizard now. What the wizard does is create or edit the '/includes/settings.php' file, but in our case we want to have the wizard create this file itself.
So the other little thing is to delete the '/includes/settings.php' file from the includes folder. If you don't delete it, you're not going to be able to get past the password thing to move on to step 2.
The big thing we need to do is to create a MySQL database on your domain, create a user for it and keep track of all that for Step 2. The Guide talks about creating the database for you but if I'm not mistaken, we cpanel type users cannot do that. (Can the folks here confirm this?) GeneralDee talk now - yes you can creating a data base direct on cpanel. To do that you have to click on mysql wizzard on your cpanel board section data base, create your data base and add an user and is password. Then now to add the table on this new data base go to myphpadmin on the same section (data base).
[edit] Database Creation
First, you're going to need to sign in to your cpanel.
Note that if you are working with more than one domain's cpanel, there is a nasty little trick lying in the weeds. You need to re-boot your PC everytime you want to switch from one cpanel to another, to clear the cache. Failure to do so may or may not be punished with really weird stuff. Take the time to do the re-boot if you want to have smooth sailing. Heck, I'm thinking it's a good idea even if you're dealing with a single cpanel.
Your hosting provider has allocated a certain number of MySQL databases, and I'm going to assume you are within the limit. On the cpanel home screen, click 'MySQL Datatabases'. When you get there, you're going to create a new database. Use whatever name you want but keep track of all of the following, write it all down because we'll need it for the wizard.
Let's use the name 'wc111' for the new database: enter that text in the box to the right of 'New Database' and then click 'create database'. Click 'Go Back' on the next screen, and note that the new database is now listed. Note that there is more to the full name of your database (at least in my case) - your cpanel user name is added in front along with an underscore character. So if my cpanel user name is 'joe', the full name of the database will be shown as 'joe_wc111'.
(This step may vary by host. On my site host, it is not necessary to create a user for the database. bbannon) Next we need to create a new user for this database, in the 'Current Users' section. Enter a Username and Password (don't lose it!) and click 'Create User'. Click 'Go Back' to, um, go back. Note that the Username also gets appended to your cpanel name with an underscore between. So if I enter 'blow' as a Username, the new Username will be 'joe_blow'. The password is one among many, this one goes with this Username.
Next we need to add this new user to this new database. Hey the next section is called 'Add Users To Your Databases', how convenient, let's use that! :-) Choose your version of 'joe_blow' and 'joe_wc111' from the drop down lists and make sure you check "ALL" under 'priveleges'. Click 'Add User To Database' and 'Go Back' one more time, and we are looking good.
[edit] We are now Wizard-Ready
[edit] Step 1
Now we are ready to run the wizard. Go to 'www.mydomain.com/WebCal/install/index.php' and you should see all green and no red (except the session counter and a red X under the green 'Safe Mode Off' text). OK? Cool. Make up a password and REMEMBER IT (maybe write it down and keep that paper private?) and enter it twice as shown. This will take you back to the same Step 1 screen, enter the password you just created and ta-da you can then move from Step 1 to Step 2 by clicking 'next'. Having fun yet?
[edit] Step 2
OK, let's see if we can do this the first time. You can try as many times as you like but it's so much more fun to just sail thru, right?
Database Type: 'MySQL' (no other choices)
Server: 'localhost' (set by default)
Login: 'joe_blow' (in this example) (Login = Database Username)
Password: (The password associated with this Database Username)
Database Name: 'joe_wc111' (in this example) (Full Database Name)
Connection Persistence: Disabled
Database Cache Directory: '/tmp' should be the default, leave it as is.
Fill all that in and click Test Settings. Ooooh, cool, it's all green, right? Under 'Database Status', You should be seeing: 'Your current database settings are able to access the database. Connection Successful Please go to next page to continue installation.'
Good to go? Click 'Next' to move to Step 3
[edit] Step 3
You should be seeing the following:
Database Status
This appears to be a new installation. If this is not correct, please go back to the previous page and correct your settings. The following database actions are required This may take several minutes to complete.'
If that's what you're seeing, go ahead and click 'Install Database'
Now you should be seeing (still on step 3):
Database Status
All your database tables appear to be up to date. You may proceed to the next page and complete your WebCalendar setup. No database actions are required'
Ain't that cool?
Click 'Next' to move to Step 4
[edit] Step 4
I recommend checking the 'Create Default Admin Account:' box so that you have a top-level Admin user that is not the same user as yourself, You may have good reasons for not doing so, what do I know?
Fill in the 'Application Name:' text box so that your Calendar Pages are properly titled in browser windows, something like 'Calendar for MyDomain.com'
'Server URL:' should be filled in; leave it alone.
'User Authentication:' I recommend leaving this alone as well, it should be set at 'Web-based via WebCalendar (default)'. You may have good reasons for choosing one of the other options, but that is beyond the scope of this HowTo article.
Read-Only should be set at 'No'
Environment should be set at 'Production' since you're a beginner and not a developer.
OK then, double-check all that and click 'Save Settings' . . . and you go right back to Step 4 BUT you now have a button to click called 'Launch WebCalendar'. Click that to go to the last step before you can start configuring your way-cool Calendar. Note that "Configuring' just means going thru all the Admin screens and making choices according to how you want your WebCalendar to behave.
The default login (assuming you checked the 'Create Default Admin Account:' box) is:
Username: admin Password: admin
Enjoy Your WebCalendar!
