Installation Instructions¶

Preparations¶

Check that the requirements are met.

Installation¶

Add limepkg-addon-installer as a dependency to your package.

Create a python module (folder) inside your python package, called installation. The installation module should contain the following:

An __init__.py file with a function called get_installation_data. The function should return an InstallationData object. Read more about the InstallationData object here.

Warning

The function definition can not be altered!

from lime_application import LimeApplication
from limepkg_addon_installer import InstallationData


def get_installation_data(
        app: LimeApplication, config: dict) -> InstallationData:
    return InstallationData(...)

An installer.py file with an Installer class that inherits from BaseInstaller specified in limepkg_addon_installer:

from limepkg_addon_installer import BaseInstaller


class Installer(BaseInstaller):
    def get_module(self) -> str:
        return <path-to-installation-module>

    def get_storage_key(self) -> str:
        return <package_name>

Extend your get_schema function in your /<package_name>/config/__init__.py file with add-on installer's Setup field:

from <path-to-installer> import Installer

def get_schema(self):
    installer = Installer(self.application)
    schema = create_schema(self.application)

    return installer.inject_installer_field(schema)

Installation Data¶

InstallationData is the object that defines everything that you want to install. Below you can see what is currently supported to install.

Database structure - defined by the database_structure key in the InstallationData object. It should be in the same format as LIP's lip.json file.

{
    "install": {
        "tables": [
            {
            ...
                "fields": [
                    ...
                ]
            }
        ]
    }
}

Security - defined by the security key in the InstallationData object. It is only possible to install users and groups. The security dict should have the following format:

{
    "users": [
        # Import UserItem from limepkg_addon_installer
        UserItem(
            # Import LimeUser from lime_authentication.users
            lime_user=LimeUser(...),

            # group names (str) this user should be a member of. The group(s)
            # must already exist or be included in the groups section below.
            group_names=[],

            # True if the password should be stored or shared with someone.
            # Don't set this if UserType is API as it will be automatically shared!
            display_password=False
        )
    ],
    "groups": [
        # Import GroupItem from limepkg_addon_installer
        GroupItem(
            # Import Group from lime_authentication.users
            lime_group=Group(...)
        )
    ]
}

View configuration - defined by the views key in the InstallationData object. The views list should have the following format:
```
[ 
    {
        "id": "webclient_views...",
        "version": ...
        "config": {}
    }
]
```
Warning

It is only possible to install views for new tables, you can not modify existing view configuration!

Warning

The view configuration needs to be compatible with the minimum lime-crm of your package, since downgrades are not supported!

Example¶

Your get_installation_data function could for example look like this if you want to install a database structure:

def get_installation_data(
        app: LimeApplication, config: dict) -> InstallationData:
    return InstallationData(
        database_structure=_get_database_structure()
    )


def _get_database_structure():
    return {
        "install": {
            "tables": [
                {
                    "fields": []
                }
            ]
        }
    }

Installer Config¶

To be able to utilize the installer config feature, an installer config schema has to be created. The schema can either be based on your regular Lime Admin config schema or it can be built customly from scratch. The installer config schema is just a standard marshmallow schema.

Base installer config on the regular Lime Admin config schema:

In most cases, the installer config schema should be a subset of your regular Lime Admin config schema. You can therefore explicitly include fields from your Lime Admin config schema to your installer config schema. This way, the amount of duplicated code will be reduced.

If you want a field from your Lime Admin config schema to be included in your installer config schema, you need to add installer_config=True as an argument to that field.
```
field = fields.Str(
    title='foo',
    installer_config=True
)
```
Build custom installer config schema from scratch:

Building a custom marshmallow schema from scratch gives you more flexibility in terms of what you want to include in your schema.

Your custom installer config schema can be passed as an argument to the installer's inject_installer_field function in your get_schema function in your /<package_name>/config/__init__.py file.

Checklist¶

You should have the following at the end of the implementation:

installation module inside your python package.
installation/__init__.py file with a get_installation_data function that returns an InstallationData object.
installation/installer.py file with an implementation of the BaseInstaller interface.
Add-on installer's Setup field should be injected in your Lime Admin config schema.
If installer config: Installer config schema can be built based on your Lime Admin config schema. A custom installer config schema can also be built from scratch and passed as an argument to the installer's inject_installer_field function.

A screenshot showing the installation folder structure.

Structure of the installation module where database structure is refactored to a separate file.