Packaging and releasing a node server

PG3(x) supports two ways of packaging a node server for release to users. It supports installations from a public github.com git repository and installations from a .zip or .tgz file. Developers have some additional options for use during development.

The rules that PG3(x) uses to determine what type of packaging and how it will access the node server to do the installation are:

if the URL contains 'pg3store.isy.io' it assumes the install will be done from a package saved to the UDI S3 storage area

if the URL ends in '.zip' it expects to find a zip package that it will unzip into the node server directory
if the URL ends in '.tgz' or .'tar.gz' it expects to find a gziped tar package that it will untar into the node server directory

else if the URL starts with 'http' it assumes the URL references a remote location and will use the HTTP protocol to access it

if the URL ends in '.zip' it expects to find a zip package that it will unzip into the node server directory
if the URL ends in '.tgz' or .'tar.gz' it expects to find a gziped tar package that it will untar into the node server directory

else it assumes the URL is a git repository and will attempt to git clone <URL> to the node server directory else if the URL starts with 'lnk:' it will attempt to make the node server directory a symbolic link to the local path specified (PG3 only, not PG3x) else if the URL ends in '.zip' it assumes the URL is a local directory path and will unzip from that path into the node server directory else if the URL ends in '.tgz' or '.tar.gz' it assumes the URL is a local directory path and will untar from that path into the node server directory else it assumes the path is a local git repository and will attempt to clone the repository to the node server directory

Using GitHub for node server deployment

Releasing a node server via GitHub uses the same basic process that is PG2 uses. First create a repository on GitHub and make it publicly accessible. Then, when submitting your node server to the store, use the GitHub URL as the Installation URL. You should also enter the branch name in the git repository that holds the release version.

PG3(x) will use the GitHub URL to create a clone of the repository in the node server's home directory when it is installed. This means all files and the file history will be cloned to the user's PG3(x) system. Take care to only include necessary files in the repository and be careful to not include any sensitive information.

PG3(x) has no way to pull tag or version info from the git repository so it will always install the latest commit for the specified branch. If you commit changes after you have made a release, those changes will be available to the next person that installs your node server.

While GitHub is the most common public hosting site used for node servers, you should be able to host a git repository on any publicly accessible server. As long as PG3(x) can do a git fetch or git clone it should work.

Using a .zip/.tgz package for node server deployment

PG3(x) also supports installing node servers from pre-packaged files. You may use ZIP or TAR to package the node server files into a single distribution package. The files should be added to the archive with no leading directories. When the package is extracted by PG3(x), it will extract them directly to the node server home directory. For example, a ZIP package listing should look something like this:

$ unzip -v udi-example3-poly.zip 
Archive:  udi-example3-poly.zip
 Length   Method    Size  Cmpr    Date    Time   CRC-32   Name
--------  ------  ------- ---- ---------- ----- --------  ----
    3734  Defl:N     1394  63% 01-19-2022 10:38 2da20043  count.py
      60  Stored       60   0% 01-19-2022 10:38 f5842ba9  install.sh
    1056  Defl:N      621  41% 01-19-2022 10:38 c64e2549  LICENSE
       0  Stored        0   0% 01-19-2022 10:38 00000000  nodes/
    3495  Defl:N     1223  65% 01-19-2022 10:38 7b59e078  nodes/count_child.py
    1010  Defl:N      533  47% 01-19-2022 10:38 69bdcd8a  nodes/count_ctl.py
     218  Defl:N      149  32% 01-19-2022 10:38 c1040ec7  POLYGLOT_CONFIG.md
       0  Stored        0   0% 01-19-2022 10:38 00000000  profile/
       0  Stored        0   0% 01-19-2022 10:38 00000000  profile/nodedef/
     662  Defl:N      210  68% 01-19-2022 10:38 18651047  profile/nodedef/nodedefs.xml
       0  Stored        0   0% 01-19-2022 10:38 00000000  profile/editor/
     189  Defl:N      120  37% 01-19-2022 10:38 edb2cb40  profile/editor/editors.xml
       0  Stored        0   0% 01-19-2022 10:38 00000000  profile/nls/
     401  Defl:N      195  51% 01-19-2022 10:38 64973c89  profile/nls/en_us.txt
     707  Defl:N      404  43% 01-19-2022 10:38 e98e2cf4  README.md
      23  Stored       23   0% 01-19-2022 10:38 c40f9bd1  requirements.txt
     953  Defl:N      478  50% 01-19-2022 10:38 50190502  server.json
--------          -------  ---                            -------
   12508             5410  57%                            17 files

You will need a publicly accessible location to host your ZIP or TAR release archive. For example, you could use a GitHub repository to hold a .zip package. However, be aware that if you let GitHub create a .zip package itself, it will include the name of repository in the file paths which prevents PG3(x) from installing the files properly.

If you don't have your own hosting site, UDI has a secure S3 storage area available for this purpose. When you submit your node server, you will enter the publicly accessible URL that points to your node server archive. If you want to store your node server in the UDI storage location, use the Choose File button to select your package and upload it. The Installation URL will be automatically filled in with the proper URL. NOTE: The URL will include the selected node server store. So make sure you have the proper store selected before you upload the file.

Using a symbolic link

If the Installation URL starts with "lnk:" PG3 will attempt to create and use a symbolic link for the node server home directory that points to the local path specified in the Installation URL. This will only work with PG3 and not PG3x and is only really viable for node servers that are in your local node server store. Also note that the path specified must be readable and writable by the user running PG3 (by default, this would be the user 'polyglot'.

For example, if you create a directory on a Polisy in /home/admin/nodeservers/mynodeserver and place all your node server files there. You could have your local store entry Installation URL be "lnk:/home/admin/nodeservers/mynodeserver". You can then make changes directly to the files in /home/admin/nodeservers/mynodeserver and they will be immediately available when you start the node server.