How to Create a SPK for Synology DSM to Distribute your LAMP

I just pack ZurmoCRM for Synology DSM successfully. It is much more complex than Asustor ADM for LAMP. There is no tools on Synology Development Tool. You have to create configuration files and use Linux tar to create packages. Here is the full story.

Download Reference and Samples

First, you need to download The 3rd Party Developer Guide on Synology Development Tool. Synology Web Developers and Synology package files might be helpful, too.

The most useful sample is official SPK, aka Synology Package, files. I download a SugarCRM-6.5-0020.spk on Index of /download/spk/SugarCRM/6.5-0020. Then use following commands to extract.

#mkdir SugarCRM
#tar -xvf SugarCRM-6.5-0020.spk -C ./SugarCRM
#cd SugarCRM
#tar -xzvf package.tgz

There is no need to register any developer account.

Create package.tgz

Create a package folder and put your LAMP applications in it.

Create a ui folder within package folder. Prepare icon files in PNG format with 9 different size for different DSM resolution: 16 x 16, 24 x 24, 32 x 32, 48 x 48, 64 x 64, 72 x 72, 90 x 90, 120 x 120, and 256 x 256.

Create a config file describing how it will be integrated into DSM. Please refer to Integrate Your Package into DSM→Config section in The 3rd Party Developer Guide for detail.

Here is the config file for my ZurmoCRM.

{
    ".url": {
        "SYNO.SDS.ZURMOCRM": {
            "type": "url",
            "allUsers": true,
            "title": "ZurmoCRM",
            "desc": "Zurmo is an easy-to-use and highly configurable CRM. It also has build-in gamification and workflow engine.",
            "icon": "ZurmoCRM_{0}.png",
            "protocol": "http",
            "url": "/zurmocrm",
            "port": "80"            
        }
    }
}

When everything is done, compress by tar with gzip into package.tgz. DO NOT CHANGE THE FILE NAME!

# cd package
# tar -czf package.tgz *

Create your Project

Create a new project folder and put package.tgz, INFO, LICENSE, PACKAGE_ICON.PNG, and PACKAGE_ICON_120.PNG files in it. PNG files are icons for your LAMP application in Package Center and during installation on DSM.

Create an empty conf folder within project folder. Although it is optional according to The 3rd Party Developer Guide, you will get an error message “Please re-install the package because something went wrong.” without it.

Create a scripts folder within project folder . It contains Linux shell scripts during installation, upgrade, and uninstall. You may use certain environment variables with scripts.

If you need interactive wizard, create a WIZARD_UIFILES folder which should contain dialog configurations.

A full description of all elements in project folder is in Synology Package→Package Structure section in The 3rd Party Developer Guide.

Here is the full tree structure of my zurmocrm project.

zurmocrm
|-- conf
|-- INFO
|-- LICENSE
|-- PACKAGE_ICON_120.PNG
|-- PACKAGE_ICON.PNG
|-- package.tgz
|-- scripts
|   |-- postinst
|   |-- postuninst
|   |-- start-stop-status
|   `-- start-stop-status~
|-- WIZARD_UIFILES
|   |-- install_uifile
|   |-- uninstall_uifile
`-- zurmocrm.spk

INFO File

A useful but not complete explanation on keys may be found in Synology Package→Package Structure→INFO section in The 3rd Party Developer Guide. Some of them are in different section. For example, dsmuidir and dsmappname are in Integrate Your Package into DSM→Config section.

Here is my INFO for ZurmoCRM. You may found more keys in SugarCRM-6.5-0020.spk and other SPK files from Synology.

package="ZurmoCRM"
version="2.7.2"
support_url="https://groups.google.com/d/forum/zurmocrm/"
displayname="ZurmoCRM"
maintainer="Zurmo Inc."
maintainer_url="http://zurmo.com/"
distributor="Amigo"
distributor_url="https://amigotechnotes.wordpress.com/"
arch="noarch"
firmware="5.0-4482"
dsmuidir="ui"
dsmappname="SYNO.SDS.ZURMOCRM"
support_center="yes"
install_dep_services="apache-web mysql"
start_dep_services="apache-web mysql"
thirdparty="yes"
support_conf_folder="yes"
description="Zurmo is an easy-to-use and highly configurable CRM. It also has build-in gamification and workflow engine."

scripts Folder

You need to learn shell scripts syntax before creating your own scripts.

For LAMP applications, a start-stop-status file is a must have or it won’t be integrated into DSM Main Menu. If you have any scripts need to be execute during installation and uninstall, put them in preinst, postinst , preuninst, and postuninst. You may mix use shell scripts with variables from wizard and environment. There are some short but useful information in Synology Package→Package Structure→scripts section in The 3rd Party Developer Guide.

I also provides files used in ZurmoCRM for your reference.

start-stop-status controls how to start and stop related services. Because I assume Apache and MariaDB are already started, I only return start or stop success in this script without checking if they are already running.

#!/bin/sh
exit 0

postinst runs after the package files are decompress and moved to /var/package. You need to manually move it to /var/service/web and change file permission and ownership or it won’t be launch by url.

In my package, I receive two variables from wizard to decide if I should create a zurmo database for ZurmoCRM and root password for MariaDB. $SYNOPKG_DSM_LANGUAGE is a DSM environment variable which may be found in Synology Package→Package Structure→Script Environment Variables section in The 3rd Party Developer Guide.

#!/bin/sh
mv /var/packages/ZurmoCRM/target/ZurmoCRM /var/services/web/zurmocrm
chown -R 1023:1023 /var/services/web/zurmocrm

echo $pkgwizard_mysql_password > $$
pkgwizard_mysql_password=`sed 's/"/\\"/gp' $$`
/bin/rm -f $$

if [ "$pkgwizard_create_database_zurmo" = "true" ]; then
    /usr/bin/mysql -u root --password="$pkgwizard_mysql_password" -e "CREATE DATABASE zurmo COLLATE = utf8_unicode_ci";
    if [ $? -eq 1 ]; then
        if [ -z "$SYNOPKG_DSM_LANGUAGE" ]; then
            echo "Fail to create zurmo database." > $SYNOPKG_TEMP_LOGFILE
            exit 0
        fi
        case $SYNOPKG_DSM_LANGUAGE in
             *)
            echo "Fail to create zurmo database." > $SYNOPKG_TEMP_LOGFILE 
             ;;
        esac
        exit 0
    fi
fi

exit 0

postuninst runs after the package is removed from DSM. You need to manually remove files and folders in /var/service/web.

#!/bin/sh
rm -rf /var/services/web/zurmocrm

echo $pkgwizard_mysql_password > $$
pkgwizard_mysql_password=`sed 's/"/\\"/gp' $$`
/bin/rm -f $$

if [ "$pkgwizard_remove_database_zurmo" = "true" ]; then
    /usr/bin/mysql -u root --password="$pkgwizard_mysql_password" -e "DROP DATABASE zurmo";
    if [ $? -eq 1 ]; then
        if [ -z "$SYNOPKG_DSM_LANGUAGE" ]; then
            echo "Fail to drop zurmo database." > $SYNOPKG_TEMP_LOGFILE
            exit 0
        fi
        case $SYNOPKG_DSM_LANGUAGE in
             *)
            echo "Fail to drop zurmo database." > $SYNOPKG_TEMP_LOGFILE 
             ;;
        esac
        exit 0
    fi
fi

exit 0

preinst runs before the package files are copied to /var/package. I didn’t use it in zurmocrm.spk.

preuninst runs before the package is removed from /var/package. I didn’t use it in zurmocrm.spk.

WIZARD_UIFILES Folder

This is optional. It contains JSON files with structure data to configure wizard dialog. Some tags may be found in Synology Package→Package Structure→WIZARD_UIFILES section in The 3rd Party Developer Guide.

I create install wizard because ZurmoCRM won’t create database automatically. It shall save time and easier to create zurmo database during SPK installation. Uninstall wizard will remove the database.

I add extra non-standard tag _comment for comments. DSM will ignore unknown tags.

[{
    "_comment": "Create zurmo database wizard.",
 
    "step_title": "Create zurmo database on MariaDB",
    "items": [{
        "type": "multiselect",
        "desc": "Do you want to you want to create zurmo database?",
        "subitems": [{
            "key": "pkgwizard_create_database_zurmo",
            "desc": "Create zurmo database"
        }]
    }, {
        "type": "password",
        "desc": "Please provide root password to create zurmo database.",
        "subitems": [{
            "key": "pkgwizard_mysql_password",
            "desc": "MariaDB root password"
        }]
    }]
}]

uninstall_uifile is very similar but to remove database.

[{
    "_comment": "Remove zurmo database wizard.",
 
    "step_title": "Remove zurmo database on MariaDB",
    "items": [{
        "type": "multiselect",
        "desc": "If you remove zurmo database, all contents will be deleted.",
        "subitems": [{
            "key": "pkgwizard_remove_database_zurmo",
            "desc": "Remove zurmo database"
        }]
    }, {
        "type": "password",
        "desc": "Please provide root password to remove zurmo database.",
        "subitems": [{
            "key": "pkgwizard_mysql_password",
            "desc": "MariaDB root password"
        }]
    }]
}]

Create SPK Package

Now, you may compress them all together as below. Remember to change zurmocrm.spk to your favorite name.

cd zurmocrm
tar -cvf zurmocrm.spk *

To automatic the build process, I create a script to compress package.tgz and zurmocrm.spk. It saves a lot of time.

cd ./package
tar -czf package.tgz *
cp package.tgz ../zurmocrm
rm package.tgz
cd ../zurmocrm
rm zurmocrm.spk
tar -cvf zurmocrm.spk *

Upload and Test

Login to your device and use Manual Install in Package Center to upload your SPK file. Test to see if it works.

After successfully installation, remember to run your LAMP application or it won’t be available in Main Menu though still accessible by url.  If it may run successfully, there should be an icon in Main Menu. You may right click on the icon and add it to DSM desktop.

Other Thoughts

If you want to make it available on Package Center, you have to submit your application with necessary document, screen shots, and SPK file to Synology in Apply Now.

I list some useful resource here to help you learn Linux shell script syntax and debug.

1. nixCraft: Linux Shell Scripting Tutorial (LSST) v2.0: If structures to execute code based on a condition
2. 鳥哥的 Linux 私房菜： 第十三章、學習 Shell Scripts：3. 善用判斷式
3. 鳥哥的 Linux 私房菜： 第十一章、認識與學習 BASH ：5.2 命令執行的判斷依據： ; , &&, ||

Reference

1. ZurmoCRM
2. Synology DSM
3. Asustor ADM
4. Wiki: LAMP (software bundle)
5. Wiki: Linux
6. Wiki: tar (computing)
7. Synology Development Tool
8. Synology Web Developers
9. Synology Wiki: Synology package files
10. Synology: Index of /download/spk/SugarCRM/6.5-0020
11. Wiki: gzip
12. Apache
13. MariaDB
14. Wiki: JSON
15. Synology: Apply Now
16. nixCraft: Linux Shell Scripting Tutorial (LSST) v2.0: If structures to execute code based on a condition
17. 鳥哥的 Linux 私房菜： 第十三章、學習 Shell Scripts：3. 善用判斷式
18. 鳥哥的 Linux 私房菜： 第十一章、認識與學習 BASH ：5.2 命令執行的判斷依據： ; , &&, ||