# Introduction

Welcome to the Kuusamo VLE documentation.

If you are new to Kuusamo, you may want to start with the [Installation](/setup/installation) guide.


# Installation

**Step 1**. Create your project using `composer`. This will install the basic set of dependencies and files.

```
composer create-project kuusamo/project
```

**Step 2**. Configure your environmental variables. This can be done by copying `config-example.php` to `config.php` and adding your own details.

```
cp config-example.php config.php
vim config.php
```

You can also use environmental variables in Apache, Heroku, or on the command line.

```
SetEnv DB_NAME "kuusamo_db"
```

**Step 3**. Install the database.

```
vendor/bin/doctrine orm:schema-tool:create
```

**Step 4**. Point your web server at the `public` directory.

**Step 5**. Open it up in your web browser and go to `/setup` to install your admin user.


# Personalisation

## Favicon

You can add a favicon by dropping a `favicon.ico` into the `public` directory. Or, if you want to specify a different location, you can use the `FAVICON` config variable to specify the path.

You can do the same thing for `apple-touch-icon.png`; there is no support for custom paths.

## Themes

Create a custom theme:

```
$theme = new Kuusamo\Vle\Entity\Theme\Theme;
$theme->setLogo('/logo.png', true);
$theme->setColour('primary', '#A71212');

Kuusamo\Vle\Service\Templating\TemplatingFactory::setTheme($theme);
```

Choose something dark for the primary colour as it will be used for links and buttons. Kuusamo automatically generates a lighter version for use elsewhere.


# Upgrading

Upgrading to the latest minor or patch version is (almost) as simple as running:

```
composer update
```

If there are `schema` changes in the changelog, you will also need to run the migration scripts to update your database. This is all handled for you.

```
vendor/bin/doctrine-migrations migrate
```

You can safely run this command whether there are migrations or not, so if you are not sure what version you are currently running, it may be best to run it every time you upgrade anything beyond a patch.

## Upgrading to 2.0

Version 2.0 adds an `exists` method to the `StorageInterface` so if you are using the AWS plugin you will need to upgrade to 2.0 on both.

## Upgrading to 1.9

Version 1.9 deprecated `footerText` in the `Theme` entity. This is now set in the admin so you should remove this function call if you have set a custom theme.

## Upgrading to 1.14

Version 1.14 contains enhancements to the `.htaccess` file that you may want to copy into youe local project.


# Courses

## Privacy

* `PRIVATE` users must be added to a course by an admin
* `OPEN` any user can join this course


# Lessons

## Marking

* `AUTOMATIC` users can mark the lesson as complete themselves
* `GRADED` multiple-choice quiz
* `TUTOR` manually marked by the tutor

## Pass mark

This is the required grade a user must reach in order to complete a lesson. This is the percentage required for `GRADED` lessons. `AUTOMATIC` lessons are automatically scored at 100 for the user.

If a lesson is optional and should not be included in the course progress percentage, set the `passMark` to 0.


# Custom error handling

If you want to log errors to an application monitoring system, you can use a custom error handler.

Register this in `public/index.php` before you cann the `kuusamo` function.

```
Kuusamo\Vle\Exception\ErrorHandler::register(function($exception) {
    var_dump($exception->getMessage());
});
```

Foe example, lets say you wanted to integrate Rollbar. Install the Rollbar library using Composer and then add the following to your `index.php` file.

```
Rollbar\Rollbar::init([
    'access_token' => 'your_access_token',
    'environment' => 'production',
]);

Kuusamo\Vle\Exception\ErrorHandler::register(function($exception) {
    Rollbar\Rollbar::report_exception($exception);
});
```

Note that custom error handlers will only run when the project is in `production` mode. During development, the exception is presented to the developer.


# Single sign-on (SSO)

Kuusamo supports single sign-on (SSO), allowing users to authenticate against an external service such as your main website.

To enable SSO, use the following config variables:

```
define('SSO_LOGIN_URL', 'https://www.mywebsite.com/login');
define('SSO_LOGOUT_URL', 'https://www.mywebsite.com/logout');
define('SSO_ACCOUNT_URL', 'https://www.mywebsite.com/account');
```

You also need to integrate it on your own website as documented below.

SSO does not manage the users within Kuusamo: you need to already have an account in Kuusamo and know the ID. Existing API functionality already exists to do all of this.

## Login

When a user tries to access the system, they will be redirected to the URL specified in `SSO_LOGIN_URL`. This login page (the login system on your main website) is then responsible for authenticating the user and logging them into the VLE.

How is this done?

Make a POST request to the Kuusamo API, `/api/sso` with the user's `ID` in the payload. The API will return an SSO token. You can then redirect the user to `/login?sso_token=<TOKEN>` and Kuusamo will do the rest. SSO tokens are valid for 30 seconds.

## Logout

When a user logs out on the VLE, their session is deleted. If the `SSO_LOGOUT_URL` variable is set, they will then be redirected to the logout page specified.

## Account

The `SSO_ACCOUNT_URL` is used for the "manage account" link.