Difference between revisions of "Lianja Package Manager"

Revision as of 08:19, 23 March 2021

Overview

Lianja Package Files (.lpk) are used to package up Apps, databases and Library files to transfer to another Lianja App Builder installation.

They can also be installed/updated automatically by the Lianja Cloud Server.

How to create a package file

Packages can be created in the Deploy workspace.

Select the data, Apps and Library files as you would to deploy them. If your files have been added to a Lianja Project, just tick the checkbox next to the Project name, and all its files will be selected.
Click the Build package button in the headerbar and enter the name for your package. There is no need to include the .lpk file extension.

Your package will be created in the packages directory.

OS	Location
Windows	C:\lianja\packages
Linux	/opt/lianja/packages
macOS	/Users/Shared/Lianja/packages

Quick Package

From Lianja v5.0 you can also create a 'Quick Package' from the Pages or Apps workspace.

This creates a package of the currently open App and saves it with the App name and version with a '.lpk' extension in the packages directory (as above).

To include database(s), Library files or multiple Apps in a single package, use the Deploy workspace instructions above.

From Lianja v5.3 the Shortcuts menu in the ModeBar includes options for Quick Project Package... and Quick Package... to allow the creation of a package file from the currently open Project or App. If the App or Project uses a database (other than the distribution southwind database), you will be prompted whether your database(s) should be included in the package.

Deployment Target Packages

From Lianja v6.0 the Deploy workspace has been enhanced to allow package files to be built for a specified deployment target.

In the Deployment configuration panel, click New to create a target or Edit to modify an existing one.
In the Package details panel, click Add Files to add the files selected in the Deployment files tree, or type the names under Files to deploy.
Prefixing a filename with '!' excludes that file from the package. Wildcard characters can also be used.

After building your package, you can share it with other Team members by uploading it to the Team repository. It will then appear in the Team workspace.

See Team Development and Release Management for more details.

How to install a package file

Lianja packages can be installed from the toolbar in the Lianja App Builder Apps workspace. They can also be installed using the LPK() function or automatically by the Lianja Cloud Server.

From Lianja v6.0, they can also be installed from the OS command line on systems with the Lianja App Builder installed.

Apps Workspace

To install a package:

Click the Install package button in the headerbar.
Select the package to install.

The installation progress will be displayed in the Console workspace and you will be prompted to confirm if a file will be overwritten.

LPK() Function

The LPK() function can be used to install or list the contents of .lpk Lianja Package Files. See LPK() for full details.

Lianja Cloud Server

The Lianja Cloud Server can automatically install or update any new packages it detects in its packages directory.

OS	Location
Windows	C:\lianja\cloudserver\tenants\public\wwwroot\packages
Linux	/opt/lianja/cloudserver/tenants/public/wwwroot/packages
macOS	/Users/Shared/Lianja/cloudserver/tenants/public/wwwroot/packages

The Lianja Cloud Server will disable user access while an upgrade is to be performed and then re-enable user access after the upgrade is complete. This is handled using LOCKRESOURCE().

If the package contains scripts called setup.prg (compiled to setup.dbo) and/or upgrade.prg (compiled to upgrade.dbo), then these are run after all the files are extracted and moved into place. This provides the ability to install on live systems and then set file permissions etc. and/or check for database schema changes. Note that from Lianja v5.0, the COMPARE DATABASE command can be used to compare two databases and automatically generate the upgrade.prg script to perform any required database schema upgrades.

The installation and update of packages creates (if it does not exist) a file packagename-install.log in the packages directory. This is a text file that contains a full history of initial installation and all updates applied. To perform an update of an existing package all you need to do is build the .lpk and upload to the packages directory.

The steps for live updating are:

Write optional setup.prg and upgrade.prg scripts.
Compile them using the button in the Script Editor or the COMPILE command.
Package up your App including these scripts, any required library files (use of lib:/thirdpartylibs is recommended) and any required database if it is a new App.
Transfer the .lpk file to the packages directory of the remote Lianja Cloud Server.
Make sure DB_WWWAUTOUPDATE is enabled on the remote server.
Access your app in the browser by logging in: the package will be installed automatically and your system updated.

OS Command Line

From Lianja v6.0, packages can also installed from the OS command line using the lianja or lianja-lpk commands.

These commands are available when the Lianja App Builder is installed.

lianja

lianja <.lpk filename>

Passing the name of a package file to the lianja command allows the package to be installed and opened in the Lianja App Builder.

It assumes that an App with the same name as the package is included in the package.

If it has already been installed and the version is the same then the App will be opened without being updated.

Windows

c:\lianja\bin>start /wait lianja c:\lianja\packages\doc_alias-1.0.lpk

Linux

$ lianja doc_alias-1.0.lpk

macOS

$ lianja doc_alias-1.0.lpk

The files from the package are listed in the terminal/command window as they are installed (Windows only).

If the package version of the App is already installed, a 'Package is already installed' message is displayed in the window.

The App is then opened in the Lianja App Builder.

lianja-lpk

List

List the contents of a Lianja package file

lianja-lpk list <.lpk filename>

Build

Create a Lianja package file

Use special prefixes such as 'app:/' and 'lib:/' for the files. Separate filelist files with ; on Windows and + on Linux/macOS.

lianja-lpk build <.lpk filename> file | filelist

Add

Add files to an existing Lianja package file

Use special prefixes such as 'app:/' and 'lib:/' for the files. Separate filelist files with ; on Windows and + on Linux/macOS.

lianja-lpk add <.lpk filename> file | filelist

Refresh

Refresh a Lianja package file with any updated files

lianja-lpk refresh <.lpk filename>

Install

Extract and install a Lianja package file

lianja-lpk install <.lpk filename> [<lOverwrite>]

By default the package file will be installed whether the App is already installed or not. If <lOverwrite> is false or .F., then existing App files will not be overwritten.

Update

Extract and install a Lianja package file

lianja-lpk update <.lpk filename> [<lOverwrite>]

If <lOverwrite> is false or .F., then existing App files will not be overwritten, otherwise they will be overwritten.

Deploy

Deploy a Lianja package file to a Lianja Cloud Server.

lianja-lpk deploy <.lpk filename> <url[:8001]>,<apikey>[,<uid>,<pwd>]

Deploy to the Lianja Cloud Server at the specified <url>. This can be directly to the Lianja Cloud Server by specifying the port :8001 on the http URL, or via IIS on Windows or Apache on Linux (http or https).

The optional <uid> and <pwd> are the username and password for a valid user on the server with admin permissions.

The <uid> and <pwd> can be omitted:

If the 'admin' user on the server has the default 'admin' password, these will be used. Note: for security reasons, the password for the 'admin' user should be changed from the default on deployed systems.
If the following environment variables are set on the deploying system and contain respectively the username and password for a valid user on the server with admin permissions, these will be used.

LIANJA_LPKUID
LIANJA_LPKPWD

Examples

Windows

lianja-lpk list c:\lianja\packages\doc_alias-1.0.lpk

lianja-lpk build webapp1-1.0.lpk app:/example_webapp1

lianja-lpk build webapp123-1.0.lpk ^
app:/example_webapp1;app:/example_webapp2;app:/example_webapp3;lib:/helloworld.prg

lianja-lpk add webapp1-1.0.lpk ^
app:/example_webapp1;app:/example_webapp2;app:/example_webapp3;lib:/helloworld.prg

lianja-lpk refresh c:\lianja\packages\doc_alias-1.0.lpk

lianja-lpk install c:\lianja\packages\doc_alias-1.0.lpk

lianja-lpk install c:\lianja\packages\doc_alias-1.0.lpk false

lianja-lpk update c:\lianja\packages\doc_alias-1.0.lpk

lianja-lpk update c:\lianja\packages\doc_alias-1.0.lpk false

lianja-lpk deploy doc_alias-1.0.lpk ^
http://win2012.lianja.local:8001,7c52c139-b88d-4756-8695-93a76264e53f

lianja-lpk deploy doc_alias-1.0.lpk ^
http://win2012.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f,admin,1$%p4ss

lianja-lpk deploy doc_alias-1.0.lpk ^
http://win2012.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f,super1,2$%p4ss

set LIANJA_LPKUID=super1
set LIANJA_LPKPWD=2$%p4ss
lianja-lpk deploy doc_alias-1.0.lpk ^
http://win2012.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f

Linux

lianja-lpk list doc_alias-1.0.lpk

lianja-lpk build webapp1-1.0.lpk app:/example_webapp1

lianja-lpk build webapp123-1.0.lpk \
app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg

lianja-lpk add webapp1-1.0.lpk \
app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg

lianja-lpk refresh doc_alias-1.0.lpk

lianja-lpk install doc_alias-1.0.lpk

lianja-lpk install doc_alias-1.0.lpk false

lianja-lpk update doc_alias-1.0.lpk

lianja-lpk update doc_alias-1.0.lpk false

lianja-lpk deploy doc_alias-1.0.lpk \
http://ubuntu20.lianja.local:8001,7c52c139-b88d-4756-8695-93a76264e53f

lianja-lpk deploy doc_alias-1.0.lpk \
http://ubuntu20.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f,admin,1$%p4ss

lianja-lpk deploy doc_alias-1.0.lpk \
http://ubuntu20.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f,super1,2$%p4ss

LIANJA_LPKUID=super1; export LIANJA_LPKUID
LIANJA_LPKPWD=2$%p4ss; export LIANJA_LPKPWD
lianja-lpk deploy doc_alias-1.0.lpk \
http://ubuntu20.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f

macOS

lianja-lpk list doc_alias-1.0.lpk

lianja-lpk build webapp1-1.0.lpk app:/example_webapp1

lianja-lpk build webapp123-1.0.lpk \
app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg

lianja-lpk add webapp1-1.0.lpk \
app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg

lianja-lpk refresh doc_alias-1.0.lpk

lianja-lpk install doc_alias-1.0.lpk

lianja-lpk install doc_alias-1.0.lpk false

lianja-lpk update doc_alias-1.0.lpk

lianja-lpk update doc_alias-1.0.lpk false

@@ Line 138: / Line 138: @@
 ====lianja-lpk====
+=====List=====
 * List the contents of a Lianja package file
 <pre>lianja-lpk list <.lpk filename></pre>
+=====Build=====
 * Create a Lianja package file
 Use [[Special Filename Prefixes|special prefixes]] such as 'app:/' and 'lib:/' for the files.  Separate filelist files with ; on Windows and + on Linux/macOS.
 <pre>lianja-lpk build <.lpk filename> file | filelist</pre>
+=====Add=====
 * Add files to an existing Lianja package file
 Use [[Special Filename Prefixes|special prefixes]] such as 'app:/' and 'lib:/' for the files.  Separate filelist files with ; on Windows and + on Linux/macOS.
 <pre>lianja-lpk add <.lpk filename> file | filelist</pre>
+=====Refresh=====
 * Refresh a Lianja package file with any updated files
 <pre>lianja-lpk refresh <.lpk filename></pre>
+=====Install=====
 * Extract and install a Lianja package file
 <pre>lianja-lpk install <.lpk filename> [<lOverwrite>]</pre>
@@ Line 157: / Line 162: @@
 By default the package file will be installed whether the App is already installed or not.  If <lOverwrite> is false or .F., then existing App files will not be overwritten.
+=====Update=====
 * Extract and install a Lianja package file
 <pre>lianja-lpk update <.lpk filename> [<lOverwrite>]</pre>
@@ Line 162: / Line 168: @@
 If <lOverwrite> is false or .F., then existing App files will not be overwritten, otherwise they will be overwritten.
+=====Deploy=====
+* Deploy a Lianja package file to a Lianja Cloud Server.
+<pre>lianja-lpk deploy <.lpk filename> <url[:8001]>,<apikey>[,<uid>,<pwd>]</pre>
+Deploy to the Lianja Cloud Server at the specified <url>.  This can be directly to the Lianja Cloud Server by specifying the port  :8001 on the http URL, or via [[ISAPI Extension for IIS|IIS on Windows]] or [[Apache Module for Linux|Apache on Linux]] (http or https).
+The optional <uid> and <pwd> are the username and password for a valid [[Users and Roles|user]] on the server with admin permissions.
+The <uid> and <pwd> can be omitted:
+# If the 'admin' user on the server has the default 'admin' password, these will be used.  Note: for security reasons, the password for the 'admin' user should be changed from the default on deployed systems.
+# If the following environment variables are set on the deploying system and contain respectively the username and password for a valid [[Users and Roles|user]] on the server with admin permissions, these will be used.
+* LIANJA_LPKUID
+* LIANJA_LPKPWD
+=====Examples=====
 * Windows
-<pre>lianja-lpk list c:\lianja\packages\doc_alias-1.0.lpk
+<pre>lianja-lpk list c:\lianja\packages\doc_alias-1.0.lpk</pre>
-lianja-lpk build webapp1-1.0.lpk app:/example_webapp1
+<pre>lianja-lpk build webapp1-1.0.lpk app:/example_webapp1</pre>
-lianja-lpk build webapp123-1.0.lpk ^
+<pre>lianja-lpk build webapp123-1.0.lpk ^
-app:/example_webapp1;app:/example_webapp2;app:/example_webapp3;lib:/helloworld.prg
+app:/example_webapp1;app:/example_webapp2;app:/example_webapp3;lib:/helloworld.prg</pre>
-lianja-lpk add webapp1-1.0.lpk ^
+<pre>lianja-lpk add webapp1-1.0.lpk ^
-app:/example_webapp1;app:/example_webapp2;app:/example_webapp3;lib:/helloworld.prg
+app:/example_webapp1;app:/example_webapp2;app:/example_webapp3;lib:/helloworld.prg</pre>
-lianja-lpk refresh c:\lianja\packages\doc_alias-1.0.lpk
+<pre>lianja-lpk refresh c:\lianja\packages\doc_alias-1.0.lpk</pre>
-lianja-lpk install c:\lianja\packages\doc_alias-1.0.lpk
+<pre>lianja-lpk install c:\lianja\packages\doc_alias-1.0.lpk</pre>
-lianja-lpk install c:\lianja\packages\doc_alias-1.0.lpk false
+<pre>lianja-lpk install c:\lianja\packages\doc_alias-1.0.lpk false</pre>
-lianja-lpk update c:\lianja\packages\doc_alias-1.0.lpk
+<pre>lianja-lpk update c:\lianja\packages\doc_alias-1.0.lpk</pre>
-lianja-lpk update c:\lianja\packages\doc_alias-1.0.lpk false</pre>
+<pre>lianja-lpk update c:\lianja\packages\doc_alias-1.0.lpk false</pre>
+<pre>lianja-lpk deploy doc_alias-1.0.lpk ^
+http://win2012.lianja.local:8001,7c52c139-b88d-4756-8695-93a76264e53f</pre>
+<pre>lianja-lpk deploy doc_alias-1.0.lpk ^
+http://win2012.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f,admin,1$%p4ss</pre>
+<pre>lianja-lpk deploy doc_alias-1.0.lpk ^
+http://win2012.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f,super1,2$%p4ss</pre>
+<pre>set LIANJA_LPKUID=super1
+set LIANJA_LPKPWD=2$%p4ss
+lianja-lpk deploy doc_alias-1.0.lpk ^
+http://win2012.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f</pre>
 * Linux
-<pre>lianja-lpk list doc_alias-1.0.lpk
+<pre>lianja-lpk list doc_alias-1.0.lpk</pre>
-lianja-lpk build webapp1-1.0.lpk app:/example_webapp1
+<pre>lianja-lpk build webapp1-1.0.lpk app:/example_webapp1</pre>
-lianja-lpk build webapp123-1.0.lpk \
+<pre>lianja-lpk build webapp123-1.0.lpk \
-app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg
+app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg</pre>
-lianja-lpk add webapp1-1.0.lpk \
+<pre>lianja-lpk add webapp1-1.0.lpk \
-app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg
+app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg</pre>
-lianja-lpk refresh doc_alias-1.0.lpk
+<pre>lianja-lpk refresh doc_alias-1.0.lpk</pre>
-lianja-lpk install doc_alias-1.0.lpk
+<pre>lianja-lpk install doc_alias-1.0.lpk</pre>
-lianja-lpk install doc_alias-1.0.lpk false
+<pre>lianja-lpk install doc_alias-1.0.lpk false</pre>
-lianja-lpk update doc_alias-1.0.lpk
+<pre>lianja-lpk update doc_alias-1.0.lpk</pre>
-lianja-lpk update doc_alias-1.0.lpk false</pre>
+<pre>lianja-lpk update doc_alias-1.0.lpk false</pre>
+<pre>lianja-lpk deploy doc_alias-1.0.lpk \
+http://ubuntu20.lianja.local:8001,7c52c139-b88d-4756-8695-93a76264e53f</pre>
+<pre>lianja-lpk deploy doc_alias-1.0.lpk \
+http://ubuntu20.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f,admin,1$%p4ss</pre>
+<pre>lianja-lpk deploy doc_alias-1.0.lpk \
+http://ubuntu20.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f,super1,2$%p4ss</pre>
+<pre>LIANJA_LPKUID=super1; export LIANJA_LPKUID
+LIANJA_LPKPWD=2$%p4ss; export LIANJA_LPKPWD
+lianja-lpk deploy doc_alias-1.0.lpk \
+http://ubuntu20.lianja.local,7c52c139-b88d-4756-8695-93a76264e53f</pre>
 * macOS
-<pre>lianja-lpk list doc_alias-1.0.lpk
+<pre>lianja-lpk list doc_alias-1.0.lpk</pre>
-lianja-lpk build webapp1-1.0.lpk app:/example_webapp1
+<pre>lianja-lpk build webapp1-1.0.lpk app:/example_webapp1</pre>
-lianja-lpk build webapp123-1.0.lpk \
+<pre>lianja-lpk build webapp123-1.0.lpk \
-app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg
+app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg</pre>
-lianja-lpk add webapp1-1.0.lpk \
+<pre>lianja-lpk add webapp1-1.0.lpk \
-app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg
+app:/example_webapp1+app:/example_webapp2+app:/example_webapp3+lib:/helloworld.prg</pre>
-lianja-lpk refresh doc_alias-1.0.lpk
+<pre>lianja-lpk refresh doc_alias-1.0.lpk</pre>
-lianja-lpk install doc_alias-1.0.lpk
+<pre>lianja-lpk install doc_alias-1.0.lpk</pre>
-lianja-lpk install doc_alias-1.0.lpk false
+<pre>lianja-lpk install doc_alias-1.0.lpk false</pre>
-lianja-lpk update doc_alias-1.0.lpk
+<pre>lianja-lpk update doc_alias-1.0.lpk</pre>
-lianja-lpk update doc_alias-1.0.lpk false</pre>
+<pre>lianja-lpk update doc_alias-1.0.lpk false</pre>
 [[Category:Developing in Lianja]]