How to install osCommerce onto your host's server.

[ArtcoInc]

(This is the first draft on instructions on How to Install osCommerce Onto a Host's Server. This is based on installing the latest osC CE edition (aka: Frozen), and NOT the 'official' v2.3.4.1 version. I'm sure others will want to include their comments and suggestions too.)

If all of this sounds too complicated, there are a number of developers here that can be hired to do all of this for you. Just post a request in the commercial area of this forum:

https://www.oscommerce.com/forums/forum/79-commercial-support-inquiries/

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

I will *assume* that your host already has PHP and mySQL (or some equivalent) installed (most hosts do). Also, most hosts will also have a set of tools SUCH AS cPanel and phpMySQL. These tools will allow you to access your area on your host's server, and administer the database . You'll also need a FTP program (such as FileZilla) installed and working on your local workstation to move files to and from the host's server, and a web browser (such as Firefox, Chrome, Internet Explorer, etc).

1) Before you begin, do you have a domain registered for your store? Do you have DNS set to point to your host's server? If not, how will you (and your customers) access your shop? Via an IP address? Best to work all of this out before you start building your store! For this example, I will assume that you do.

2) Using a browser on your workstation, log into your account on your host's server. Remember what username and password you used, as you will need this again later. Write these down!  Using whatever tools your Host provides, access the area where you will be storing your files. Your host will have an area for you called something like /public_html/. If you're not sure, ask your host. Your host may allow you to have more than one domain within your account. If this is something you might want, ask first! You are going to have to have a place for your store's files. You could put them in the your root directory (such as /public_html/), but I suggest you create a sub-directory specifically for your store. If you have a domain name already registered, good practice would be to name this sub-directory the same as your domain (ex: /public_html/<my domain name>/). Use whatever tool your host offers to create this sub-directory.

3) Within this sub-directory, it is good practice to create another sub-directory called /catalog (your directory structure would look something like /public_html/<my domain name>/catalog). Some developers here disagree with this, but it does make things easier if, in the future, you want to add something like a blog, etc. to your domain.

4) Once the directory structure is set up, it's time to set up the database. Using whatever tool your host offers (such as phpMyAdmin), create a database for your store. Your database will have to have a name, a database administrator's name, and a database administrator's password. Write these down!. You will also be given an option of setting the Collation. This is the method by which the database encodes and stores the data. Choose utf8_unicode-ci. You can now log out of your host's server.

5) With the server all set up, it's time to begin moving files to the server. Download the latest copy of osCommerce onto your workstation. Extract all of the files from within the ZIP'd file into a clean directory. There will be a LOT of files (over 1400 of them) and LOTS of sub-directories. It is important to keep the files and directory structure intact. Make a note of where you have extracted these!

6) Launch your FTP client on your local workstation. A very popular one is called FileZilla. You will need to download and install this on your workstation before you can use it. Launch it, and point the LOCAL site to the directory where you extracted all of the osCommerce files (you wrote this down, didn't you?). Point the REMOTE site to your host's server. You will need whatever username and password your host gave you in order to connect to their server (you wrote these down, didn't you?). Be sure to point to the sub-directory you created in steps 2 and 3 above!

7) You will now need to transfer ALL of the extracted files from your workstation to your host. This can take some time, depending on the speed of your internet connection. After all of the files have been transferred, you can log out of your FTP client.

8) Launch your browser. Point it to your host's server, using whatever method you set up in step 1 above. For example, point your browser to <my domain name>.com. IF you put all of your store files in the /catalog sub-directory (as recommended), you will need to include that too (ex: <my domain name>.com/catalog).

This should launch the installation program. If it doesn't, stop and figure out why (because you can't continue on otherwise).

9) There are several steps in the installation ...

  a) The first screen will tell you if the server is capable of running osCommerce. It will check that PHP is installed, which version, and that it is configured correctly. It will also check that mySQL is installed, and all of the appropriate extensions are installed. This will be a pass/fail test.

Either the server passes, or it fails. If it fails, you will need to contact your Host to resolve the problem ... this is not something you can fix. If it passes, click on the big green "Start the installation" button.

  b) This step configures the database.

    b1) The first field is the database location. It is typically either 'localhost' or the IP address of the database server. Ask your Host if you are not sure.

    b2) This is the Database Administrator's name (you wrote this down, didn't you?)

    b3) This is the Database Administrator's password (you wrote this down, didn't you?)

    b4) This is the database name (you wrote this down, didn't you?)

Once these are all filled in correctly, click on the big green 'Continue to Step 2' button. The program will build the database tables, and pre-fill in all of the necessary data. This can take some time. Be patient!

  c) The next step defines where the store is on the web server. If you got this far, the default answers are probably correct. Click on the big green 'Continue to Step 3' button.

  d) This is where you configure your store information.

    d1) What is your Store Name. This will show throughout your store, on invoices, emails, etc.

    d2) If you want to personalize your store, you can put your name here, and your name will show on invoices, emails, etc. Otherwise, enter something like 'Store Owner'.

    d3) This is the email address for people wanting to send emails to your store. Enter a valid email address.

    d4) This is where you enter the name of the Administrator for your store. You need at least one Administrator. Later on, you can create more administrators, if you wish. It can be a real person's name, or any word you make up (such as 'Boss'). Write this down! Do note that this is the Administrator for your STORE, and is separate from the Administrator for the DATABASE.

    d5) This is where you create a password for the first Administrator. As with any password, it should be something that is not easy to guess (don't use 'password' as your password!). Write this down! Again, note that this is the password for the STORE administrator, which is separate from the DATABASE administrator.

    d6) This is the sub-directory name where all of the administrative files are located. The default name is 'Admin'. While you may leave it as the default name, for better safety, it is better to change this to something a little less obvious. Write this down!

    d7) This is where you set the time zone for your store. If you are in Japan, the US, or the UK, you will be in different time zones. You want the time in your store (as recorded on orders, etc) to be correct for where you are. Select the closest city from the drop-down list.

Once you have everything filled out, click on the big green 'Continue to Step 4' button.

  e) If everything went well, you should be greeted by a 'Finished' screen. Across the bottom are two big buttons: The Green button will take you to your store front. The blue button will take you to your Administration side of your store. You will need your store's Administrator's name and password to enter here (you wrote those down, didn't you?).

Congratulations! Your store is now online! It will be filled with some sample products. You will need to go into the Administration side of your store to configure your store (turn on features, arrange things, add new products, etc.)

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Again, if all of this sounds too complicated, there are a number of developers here that can be hired to do all of this for you. Just post a request in the commercial area of this forum:

https://www.oscommerce.com/forums/forum/79-commercial-support-inquiries/

Good luck!

[MrPhil]

Trying to approach this from the viewpoint of someone who has never set up a website before, I'd like to offer a few clarifications.

Point 0:  If you have a choice with your host, try to get on a Linux + Apache server rather than a Windows server. It will generally be cheaper and perform better, as a lot of tools and applications were written with Linux + Apache in mind. It's not a deal-breaker, but expect some incompatibilities and minor problems if you choose Windows. The only real reason to choose Windows over Linux is that you're planning to do a lot of MS back-office stuff (with ASPX, Access, etc.).

cPanel is not a generic term, but a specific brand of control panel (there are many others that are functionally more or less equivalent). Don't get confused in your terminology. Nor should you get confused between an application's "control panel" (a.k.a. dashboard) and your hosting control panel -- they're separate things.

At this point you should also be deciding whether you'll be referring to your domain as "www." or not (you should be consistent), and whether you'll be putting the entire site under SSL (https). Many hosts now offer SSL for free, so there's really no point in not using it. osCommerce will at a minimum try to use SSL for certain pages with sensitive information, but nowadays Search Engines will penalize you for not having SSL on all pages, so you might as well go for it.

Point 2: Hosts will provide you with an ID and password to get into your hosting control panel, from which you can load files into your site. A control panel with have a means to upload (and maybe download) files, edit files, change their permissions, and other operations. In the long run, you will probably be happier with your favorite editor on your PC and an FTP client such as FileZilla (which may use the same ID/pw as the control panel, or have a different one -- ask your host), but what the control panel provides can do in a pinch.

Note that many hosts will not permit an FTP client to change permissions -- you'll need to use the hosting control panel to do that.Speaking of which, at some point you'll need to understand the concept of permissions, and what you need for your site to operate. My advice is to start out with the most restrictive permissions you can (read-write for the owner, read-only for everyone else), and then loosen them up as you find it necessary. For instance, for installing and having an application configure itself, it will usually need to be able to write to directories and files, which means that PHP (the language platform that osC uses) may need to be granted looser permissions (read-write) if it's not "running" masquerading as the owner. It all depends on the Operating System and the Web Server software being used. You may need to do some experimentation or talk to your host if things don't seem to be working as expected. A final note: stupid people will blithely tell you "just chmod 777 everything". Don't. That's unlocking all the protections and allowing anyone else sharing your server (and even possibly those coming in via a browser) to overwrite or erase your files! Keep it locked down as much as you can without interfering with what it needs to do.

Not all web servers will use "public_html/" as the "root" directory to your site (what is seen as "/" directory by HTML). That is the standard for Apache, but other servers use other names. "Above" this directory (its parents), no one has access from the Web. At or below this directory, anyone on the Web can get to, permissions allowing. Note that tools like "robots.txt" and "nofollow" and "noindex" attributes are merely suggestions to search engines and other 'bots... they offer no real security on their own.

I don't know why Malcolm is suggesting you put two layers of directories under public_html/ (<domain name>/, and catalog/ in Point 3). That may be an error. I'll address this further in Point 3.

Point 3: It is a very good idea to put a major application such as a store into its own subdirectory under public_html/. However, I've never seen a need to use more layers (as Malcolm suggests). The default for osCommerce is catalog/, but you can choose store/ or anything else. Remember, it will be visible to users, so don't get carried away with it! Some people will tell you to install the store directly under public_html/ (so it's /index.php rather than /catalog/index.php), but that has its problems. If you ever want to install another application, it will have to go "through" your store, or at least, through its .htaccess file. That can be a problem in that you often have to heavily modify .htaccess to get it to stop molesting URLs intended for other applications, or you end up anyway having to move your store down into catalog/, losing all your hard-earned Search Engine points in the process. You also end up cluttering up your root (public_html/) directory with all sorts of application-specific files, which means manually untangling them when you want to upgrade or even remove that application. Keeping an entire application in its own subdirectory tree cleanly isolates it, so it won't stomp on other applications and vice-versa.

Probably the primary reason that people will tell you to install directly into the site root (at public_html/) is that it's a nuisance for visitors to have to type in that extra catalog/ or shop/ into the URL. That's easy enough to deal with -- as long as the store is the only thing on your site, most servers will permit you to "rewrite" a URL to the root down to the catalog/, in .htaccess:

RewriteEngine On
	RewriteCond  %{REQUEST_URI}  !^/catalog  [NC]
	RewriteRule  ^(.*)$  /catalog/$1  [L]

Visitors will see that they've been transferred to catalog/, but no big deal. When the time comes to add more applications, as well as a "landing page" in the root to introduce the site and offer links to the various applications on it, all the current bookmarks and search engine entries will still be valid. You would of course remove this URL rewrite. Some servers use a different way, but that's the most common.

While you're in /.htaccess (root's .htaccess, as opposed to /catalog/.htaccess for the store), you'll want to force use of (or removal of) incoming "www." on the domain name, and forcing SSL (https) if you want to use it site-wide. This would involve a "301" redirect of the URL if someone doesn't type it in the desired way. There's also blocking of the IP addresses of troublemakers, and various other general things. Leave osCommerce SEO rewrites, etc. to /catalog/.htaccess, obeying the principle of cleanly separating applications from the overall site.

This is getting a bit long, so I'll resume with another post.

[ArtcoInc]

@MrPhil

Thank you for the clarifications.

As I stated at the very beginning, this was a first draft. In another thread, someone asked how to install osC outside of using the one-click install their host offered (which would have installed the older 'official' version). Since I did not know of any instructions, I thought it important to write up some. Ultimately, I'd like to see this fully expanded, and pinned somewhere here in the forum.

I do acknowledge that different people have different preferences as to how they set up their store. This is fine. I think it is important that new store owners are aware of these different preferences, that they are just preferences, and they can make an informed choice for themselves.

To you, and all other experienced developers and/or store owners, let's see if we can work together to get this available as a (hopefully valuable) tool for new store owners.

Thanks!

Malcolm

[MrPhil]

Point 4: Different hosts do database setups in different ways. They may have a separate control panel section to create a database and its user (a.k.a. DB administrator). They may also require you to "grant" privileges to that user, and explicitly associate that user with a specific database. They often will not permit an application (such as osCommerce) to create a database or perform some operations on it, in the name of security. These need to be done via the control panel. Some unfortunate people end up on servers where they can create only one database for all their applications. This will slow down operations and there may be conflicts between applications if they try using the same table names. Hopefully you can add a prefix to table names to keep application data separate. Note that this is a different prefix than that which is frequently required in the PHP database interface, where many hosts have the account name and an underscore _ prepended to the database name, user, etc. Never give out this prefix (account name) in a forum posting, as it makes it much easier to break into your account!

"Collation" is something of a misnomer. There are two things going on here with the database: the character encoding used (which these days should be UTF-8 rather than Latin-1), and its collation (how text fields are sorted -- by a particular language's standard, whether to sort 'A' and 'a' as the same or distinct, or even by binary values, etc.). "utf8_unicode-ci" is pretty common and generic for UTF-8, with upper/lower case ignored (treat 'A' and 'a' the same).

The most common database (relational database management system) is MySQL (note the capital M), and specifically you will be using the MySQLi (improved) version. Some hosts are dropping MySQL (now owned by the Evil Empire, Oracle) in favor of the very similar fork, MariaDB. I don't know offhand what the status is with osCommerce trying to use SQLite, postGREsql, and other freeware database engines. By the way, "My" is not really the English personal possessive pronoun -- it's the name of the daughter of one of the original Swedish creators of the database, as is "Maria". Anyway, if your host does not have MySQLi, you may have some work ahead of you to fix things!

Point 5, 6, 7: Some hosts will allow you to upload (either from the control panel or via an FTP client) the .zip file, and then unpack (unzip) it on the server. This is acceptable, just as long as you check where the files ended up! Most control panel file uploads only deal with one file at a time, so uploading hundreds of files gets rather tiresome. FTP clients will give you a way to mark multiple files and upload them in one operation, so you can do it either way.

Note that it's a good idea to keep a copy of all your files on your PC (workstation) as a backup, but be sure that any files you (or the install process) modify on the server get copied back to your PC, so your backup is up to date. Also note that this is a backup of your files, and does not include your database, which is a separate backup.

Anyway, you need to make sure that you uploaded your files to the intended place, and preserved the file structure (e.g., includes/ under the store root catalog/). You don't want to end up with all your files in one ginormous flat directory! You may need to adjust your directory and file permissions before going any further, typically (on a Linux + Apache server) 755 for directories and 644 for files, although this may vary by host and specific server, and some may do things differently. These permissions are read-write for the owner (who has the right to change files) and read-only for everyone else.

Point 9d6: it is actually very important for you to use something other than Admin as the administration name. You will unfortunately find that you have hacker scum constantly trying to break into your administration area, and if you leave it as Admin, that's half the battle for them. At least make it harder for them to get a foot in the door (and start guessing IDs and passwords) by giving some weird randomish name to the directory. And NEVER tell anyone else your new Admin name, especially in postings to this forum! Be careful if you copy and paste something into public view that you obfuscate the real Admin name (such as changing it back to 'Admin'). The same goes for database access sections of your configure.php files -- obfuscate the user name and password (and probably the database name too) before posting!

Your admin section should also be protected by server "password protection", which will require another ID and password (demanded by the server, not by osCommerce) to let you in. While osC does provide some sample code for this, it doesn't always work. If it doesn't, remove it and use your hosting control panel's "password protect a directory" function to generate the right code entries for this. The only advantage to using the password protection suggested by osC is that it will (usually) pass the Security Check you can run in osC admin, while host-provided protection frequently will "fail" the test. If in doubt, if you try to go into your protected area and the server demands an ID and password, it's working OK and there's no need to lose sleep over what Security Check says.

Point 9 somewhere: note that there are two different "configure.php" configuration files. One is in /catalog/includes/ and the other is in /catalog/<Admin>/includes/. They will both be updated by the installation process, so you may have to adjust file permissions to allow PHP to write to them during installation. You should then return them to their normal permissions after installation, or even to "read-only" (e.g., 444) so that they can't accidentally be wiped out. If you immediately backed them up to your PC, that's not as critical to do, but it's still a good practice. Finally, they're different. Take care not to upload one over the other, as careless or naive people frequently end up doing!

Congratulations: Your store comes with a bunch of preloaded sample products. Don't forget to remove them when you're ready to start loading in your real products. It's best to use the Admin product management pages to delete them (and their categories) one by one, especially if you're inexperienced at this, rather than daringly going directly into the database and truncating product tables. Maybe some day osC will get a utility or function to remove all sample products (or even add them back) without all the tedium.