This section deals with installing Kartris and doing some basic configuration.

There are two main scenarios for setup – local and remote. 'Local' means installation on a computer you have full access to such as your desktop or laptop computer, or a server if you have full admin rights. 'Remote' means a computer you can only access via FTP and MS SQL.

Our site downloads page has links to download the latest build from Microsoft's Codeplex site.

http://www.kartris.com/t-Downloads.aspx

The software itself comes as a zipped file.

Don't forget to unblock any zip files you download before you unzip them.  More information...

You must have the following software installed in order to run Kartris.

  • IIS7.x (Windows Server 2008 or Vista) or IIS8 (Windows Server 2012 or Windows 8 or above)
  • MS SQL 2008 Express or above (available free from Microsoft's web site) or one of the full versions of MS SQL 2008 or above
  • ASP.NET 4.5+
For best performance, a modern browser such as Firefox, Chrome, Safari or IE9+ for the back end.

Kartris 2.0 and onwards are licensed by default with the GNU General Public License v2 (normally abbreviated to GPL v2). This is a free open-source license. Please read the license terms carefully - in particular, the license requires you to ensure that you do not remove code that displays copyright and warranty information to users. So the 'powered by' link at the foot of pages must be retained under this license.

This license permits removal of the 'powered by' link from Kartris sites for the domain or subdomain for which it is purchased. There is no expiry date on the license, so you can use this with future Kartris releases - once your domain is licensed, you can upgrade to a newer Kartris version and continue to use this license.

There are various ways to install Kartris depending on your circumstances.

Kartris is featured within the Microsoft Web App Gallery. Various Microsoft Tools including IIS and Web Matrix make it simple to install Kartris.

Install - Microsoft Web Platform Installer

The process on IIS7 and earlier will be similar, the main difference being that the web site will run as a specific Windows user rather than an app pool identity. So you will need to add that user to your SQL Server, and create Windows permissions for it.

Firstly, you must have Windows, IIS and SQL Server installed. This example is using Windows 8.1 and SQL Server 2008 R2. But the process will be similar for other versions of Windows with IIS7 or above.

Step 1 - Find where your IIS web root folder is and add a new folder into it. If you're not sure where it is, go to IIS, right click the Default Web Site and select 'explore'. The default location is normally C:\inetpub\wwwroot, but you can move this to another location for disk space reasons, or locate it into your Dropbox if you want files to be backed up to the cloud.

Step 1 - Find web root

Step 2 - Within windows explorer, add a new folder into your web root. We tend to use names that help identify the version of Kartris and the name of the customer or site, to make it easier to tell these things at a glance later.

Step 2 - Create a new folder for the web

Step 3 - Back in IIS, refresh the sites and you should see the new folder within 'sites'. Right click this, and select 'Convert to Application'. A dialogue pops up. Click the 'Select' button and choose the ASP.NET 4.0 or ASP.NET 4.5 application pool. Then Ok everything. You should see the folder 'k26001_mytestweb' icon change. The web is now set up ready for our files, which will come a bit later.

Step 3 - Convert to application

Step 4 - We need to create a new database for our site. Open up SQL Management Studio and connect. If you are using SQL Express, the default location will be localhost\sqlexpress. Right click on the 'Databases' folder and select 'New Database'. Name your database and save - again, we're going to call it 'k26001_mytestweb' (the name does not have to match your web, but it's much easier to tie up sites to their respective databases later if it does).

Step 4 - Create a new database

Step 5 - We need to create the right permissions to allow our web to work with this database. This part is all about identifying which Windows user your web runs as, and giving this user permissions. Because we set the site up using the defaults, it should be running as an app pool identify user called 'IIS APPPOOL\.net v4.5. Remember the application pool we selected in step 2 above was called '.net v4.5' - the database user you need will be called 'IIS APPPOOL\[application pool name]'.

To find users on this database, open up the 'Security' folder in SQL Management Studio and then 'Logins'. If you don't see 'IIS APPPOOL\.net v4.5' (or whatever the name of your app pool is), then you need to add it. If you see the user there already, you can skip to the next step. Otherwise, right click on 'Logins' and type the name of the app pool into the dialogue, then 'Search'. Another window appeals, and you need to enter 'IIS APPPOOL\.net v4.5' again into the box here. When you click 'Check names' you should see the text change, hiding the IIS APPPOOL part. This indicates that it is a valid user. OK everything, and this new user should now appear under 'Logins' in the treeview.

Step 5 - Add the database user

Step 6 - We need to map this database to this user. Right click on the 'IIS APPPOOL\.net v4.5' user and select 'Properties'. On the dialogue that pops up, select 'User Mapping'. Check the box by the 'k26001_mytestweb' database and Ok to save. This means that this user is now mapped to this database.

Step 6 - Map user to database

Step 7 - Now we have the user mapped to this database, we need to give him permissions. Go to k26001_mytestweb > Security > Logins and then right click on the app pool user. In the popup, select 'db_owner' in the 'Database role membership field'. Then OK.

Step 7 - Giving the db user permissions

Step 8 - Now we are all set to copy in the Kartris files. Download the latest zip, and ensure you unblock it (see here for more info). Open it up and copy the contents of the Kartris folder into the 'k26001_mytestweb' folder. Your folder should look like this:

Step 8 - Import files from zip

Step 9 - The final configuration step is to give the web site user full control permissions. This is so the web site can write, modify and delete files, which is essential as you upload product images, make changes to payment systems. It also means that the install routine can rewrite the web.config file itself, which makes things a bit easier.

To do this, find the web root in Windows explorer, right click the k26001_mywebsite folder, and select 'properties', then the 'security' tab.

Step 9 - Set Windows permissions

Click the 'Edit...' button, then 'Add...' and enter 'IIS APPPOOL\.net v4.5'. Ok this, and the user '.NET v4.5' should appear in the list.

Step 9a - Adding Windows user

Finally, select this user in the list and give it full 'allow' permissions, and then OK everything.

Step 9b - Set permissions

Step 10 - You now have the database and web set up with full permissions, and should be ready to start the installer. Call up the web site in a browser - the URL will be http://localhost/k26001_mytestweb/.

Step 10 - Run the setup routine

  1. Unzip Kartris to a folder on your desktop. Using FTP, upload the files to your web site.
  2. Make sure your hosting is set to run as ASP.NET 4.0.
  3. Call up the site in your web browser, and the setup routine should run.
  4. When you get to the stage to setup the database connection, you will probably need to use the database address (or IP), name, username and password given to you by your web host. The install routine will try to rewrite your web.config file with these connection details, but if the permissions do not allow this, you can download it from the setup routine and then upload to the root of your site with FTP instead.
  5. If you get problems running the database setup and want to create the database first through MS SQL's Management Studio interface, the .sql file is located here:

    Uploads/Resources/kartrisSQL_MainData.sql

    When you run the setup routine again, it should notice that you already have a Kartris database populated.
  6. Once setup and logged in to the back end, you can go to the front end by clicking the Kartris logo link in the top left of the page.

Sometimes you might want to run the install routine again – for example, to reset the admin password for Kartris if you forget it. You can do this by making a couple of minor changes to the web.config file.

First, change the connection string to a non-existent database:

<add name="KartrisSQLConnection" connectionString="Data Source=localhost\SQLEXPRESS;Database=BadDBName;Integrated
Security=True;connect timeout=50" providerName="System.Data.SqlClient"/>

Secondly, comment out the 'globalization' tag. This is what tells Kartris where to find language localization strings. The install routine uses a file for these, but once Kartris is up and running and connected to a database, it pulls this data from the database instead. Check there is no other 'globalization' tag nearby in the code which is uncommented.

<!--<globalization resourceProviderFactoryType="Kartris.SqlResourceProviderFactory"
 culture="auto" uiCulture="auto" enableClientBasedCulture="true"/>-->

If you wish to upgrade an existing Kartris site to the latest version, then you need to proceed as follows:

  1. Download and install the latest Kartris to a new web.
  2. Create a new database by restoring a backup of your old Kartris database.
  3. Run the update SQL scripts on the database with SQL Management Studio to take it up to the latest version. These scripts are located in the new Kartris web, at this location:

    /Uploads/Resources/

    You need to run the scripts necessary to take your database from its present version, to the latest version, in the right order. For example, if upgrading a v1.4001 to v2.5003, you would need to run these SQL updates on the database in this order:

    UpdateSQL_1.4001_To_1.4002.sql
    UpdateSQL_1.4002_To_2.0000.sql
    UpdateSQL_2.0000_To_2.0001.sql
    UpdateSQL_2.0001_To_2.0002.sql
    UpdateSQL_2.0002_To_2.5000.sql


    There is not necessarily an SQL script for each Kartris release; one is only required if there were database changes. So in this case, we've upgraded the database to v2.5000, because that is the latest version of the database. Similarly, if you were upgrading v1.4004, you would need to start with the UpdateSQL_1.4002_To_2.0000.sql upgrade script, to ensure you get all the required changes.

    You may get errors show up in the console during the upgrade process, but generally you can ignore these. It's normally because you have new language strings or config settings already for some reason, and so trying to add these in fails. But everything else should still be able to run, and since you have the required records already, there should be no problem.

  4. Hook up your new web to the new upgraded database. To do this, edit the web.config file to make the following changes (a) database connection (b) ensure that the 'globalization' tag is uncommented (see 2.4.4. Forcing the install routine to run again for more details).
  5. You should also copy the 'hashsalt' value from the app settings near the top of your new site web.config file. If you don't do this, you may find your back end login no longer works.
  6. You should now be able to import your old skin to the Skins folder, and set up your site to use this from the back end.
  7. If you changed any user controls or code in your prior version, you can try to import this to the new site. But be aware that they may not be compatible, or that by importing older files, you may lose newer functionality which we've added to the new version.
  8. Other parts of the old site that will probably need to be imported too:
    - Images folder, Uploads folder (except Logs, Resources, Temp)
    - the .sitemap files in the root (these format navigation menus on your skin as well as breadcrumb hierarchy)
    - any robots.txt in the web
    - the .config files from any payment systems you have setup, these are stored in the relevant folder within /Plugins and hold the payment gateway configuration for that payment system).

Powered by tomeCMS