@beezwax/bzbond-server v0.9.45

Introduction

bzBond-server is a microservice for Claris/FileMaker Server that enables execution of JavaScript code. It also acts as a host for additional microservices, called Microbonds.

Table of contents

• Installation
  • Installation on macOS/Linux
  • Installation on Windows Server
  • Installation with a proxy on macOS/Linux
  • Installation with a proxy on Windows Server
• Updating
• Usage
• Microbonds
  • Microbond installation
    • Microbond installation on macOS/Linux
    • Microbond installation on Windows Server
    • Microbond installation with command line arguments
      • Example of Microbond installation command including name and source url on macOS/Linux
      • Example of Microbond installation command including name and source url on Windows Server
    • Microbond installation local git repo url format
      • Examples of local git report url format for Microbond Installation on macOS/Linux
      • Examples of local git report url format for Microbond Installation on Windows Server
    • Microbond installation with a proxy on macOS/Linux
    • Microbond installation with a proxy on Windows Server
  • Microbond update
    • Microbond update on macOS/Linux
    • Microbond update on Windows Server
    • Microbond update with a proxy on macOS/Linux
    • Microbond update with a proxy on Windows Server
  • Microbond creation
    • Microbond creation on macOS/Linux
    • Microbond creation on Windows
    • Microbond creation: Namespacing
  • Microbond publishing
  • Microbond uninstallation
    • Microbond uninstallation on macOS/Linux
    • Microbond uninstallation on Windows Server
• Logs
  • bzBond-server logs on macOS/Linux
    • Viewing bzBond-server logs on macOS
    • Viewing bzBond-server logs on Linux
  • Viewing bzBond-server logs on Windows Server
• Uninstallation
  • Uninstallation on macOS/Linux
  • Uninstallation on Windows Server

Installation

These installations assume a default installation of Claris/FileMaker Server on the specified platform.

Installation on macOS/Linux

On macOS or Linux use the following command to install bzBond-server:

curl -o- https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/install.sh | bash

Installation on Windows Server

Note: Install node and git before installing bzBond-server.

On Windows Server use the following command in PowerShell to install bzBond-server:

powershell Invoke-WebRequest https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/install.ps1 -OutFile "$($env:USERPROFILE)\AppData\Local\Temp\install.ps1"|powershell -File "$($env:USERPROFILE)\AppData\Local\Temp\install.ps1"

Installation with a proxy on macOS/Linux

On macOS/Linux reference the proxy in the installation command as follows:

curl -o- https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/install.sh | bash -s -- -x http://proxy.address.com:port#

For example:

curl -o- https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/install.sh | bash -s -- -x http://proxy.example.com:443

Installation with a proxy on Windows Server

On Windows Server reference the proxy in the installation command as follows

powershell Invoke-WebRequest https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/install.ps1 -OutFile "$($env:USERPROFILE)\AppData\Local\Temp\install.ps1"|powershell -File "$($env:USERPROFILE)\AppData\Local\Temp\install.ps1" -Proxy http://proxy.address.com:port#

For example:

powershell Invoke-WebRequest https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/install.ps1 -OutFile "$($env:USERPROFILE)\AppData\Local\Temp\install.ps1"|powershell -File "$($env:USERPROFILE)\AppData\Local\Temp\install.ps1" -Proxy http://proxy.example.com:443

Updating

Use these instructions to update bzBond-server to the latest version

Updating on macOS/Linux

On macOS or Linux use the following command to update bzBond-server:

curl -o- https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/update.sh | bash

Updating on Windows Server

On Windows Server use the following command in PowerShell to update bzBond-server:

powershell Invoke-WebRequest https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/update.ps1 -OutFile "$($env:USERPROFILE)\AppData\Local\Temp\update.ps1"|powershell -File "$($env:USERPROFILE)\AppData\Local\Temp\update.ps1"

Updating with a proxy on macOS/Linux

On macOS/Linux reference the proxy in the update command as follows:

curl -o- https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/update.sh | bash -s -- -x http://proxy.address.com:port#

For example:

curl -o- https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/update.sh | bash -s -- -x http://proxy.example.com:443

Updating with a proxy on Windows Server

On Windows Server reference the proxy in the update command as follows

powershell Invoke-WebRequest https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/update.ps1 -OutFile "$($env:USERPROFILE)\AppData\Local\Temp\update.ps1"|powershell -File "$($env:USERPROFILE)\AppData\Local\Temp\update.ps1" -Proxy http://proxy.address.com:port#

For example:

powershell Invoke-WebRequest https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/update.ps1 -OutFile "$($env:USERPROFILE)\AppData\Local\Temp\update.ps1"|powershell -File "$($env:USERPROFILE)\AppData\Local\Temp\update.ps1" -Proxy http://proxy.example.com:443

Usage

For details on using bzBond-server see the bzBond-claris documentation for running JavaScript functions with the bzBondRelay script (client and server).

Microbonds

Microbonds are custom endpoints in the bzBond-server microservice that extend its capabilities. Microbonds can perform specific tasks, interact with external APIs, or provide an interface for other applications installed on the server.

Microbond installation

Microbond installation on macOS/Linux

On macOS/Linux use the following command to install a Microbond:

/var/www/bzbond-server/bin/install-microbond.sh

Microbond installation on Windows Server

On Windows Server use the following command to install a Microbond:

powershell -File "C:\Program Files\bzBond-server\bin\install-microbond.ps1"

Microbond installation with command line arguments

The installer will prompt for the Microbond name and source url. The Microbond name and source url can also be provided as command line arguments.

Example of Microbond installation command including name and source url on macOS/Linux

/var/www/bzbond-server/bin/install-microbond.sh bzmb-hello-world https://github.com/beezwax/bzbond-server-microbond-example

Example of Microbond installation command including name and source url on Windows Server

powershell -File "C:\Program Files\bzBond-server\bin\install-microbond.ps1" bzmb-hello-world https://github.com/beezwax/bzbond-server-microbond-example

Supported URL formats are full GitHub URLs (as shown above), or a path to a local git repository.

Microbond installation local git repo url format

Examples of local git repo url format for Microbond installation on macOS/Linux

/home/my-username/a-microbond-git-repo

../some-folder/a-microbond-git-repo

Examples of local git repo url format for Microbond installation on Windows Server

C:\Users\my-username\a-microbond-git-repo

..\some-folder\a-microbond-git-repo

Microbond installation with a proxy on macOS/Linux

On macOS/Linux reference the proxy in the installation command as follows:

/var/www/bzbond-server/bin/install-microbond.sh -x http://proxy.address.com:port#

For example:

/var/www/bzbond-server/bin/install-microbond.sh -x http://proxy.example.com:443

When installing on macOS/Linux with command line arguments and a proxy either positional or named parameters must be used, they cannot be mixed.

Positional example:

/var/www/bzbond-server/bin/install-microbond.sh microbond-name url http://proxy.example.com:443

Named example:

/var/www/bzbond-server/bin/install-microbond.sh -n microbond-name -u url -x http://proxy.example.com:443

Mixed example (will not work):

/var/www/bzbond-server/bin/install-microbond.sh microbond-name url -x http://proxy.example.com:443

Microbond installation with a proxy on Windows Server

On Windows Server reference the proxy in the installation command as follows:

powershell -File "C:\Program Files\bzBond-server\bin\install-microbond.ps1" -Proxy http://proxy.address.com:port#

For example:

powershell -File "C:\Program Files\bzBond-server\bin\install-microbond.ps1" -Proxy http://proxy.example.com:443

Microbond update

Microbond update on macOS/Linux

On macOS/Linux use the following command to update a Microbond:

/var/www/bzbond-server/bin/update-microbond.sh microbond-name

Microbond update on Windows Server

On Windows Server use the following command to update a Microbond:

powershell -File "C:\Program Files\bzBond-server\bin\update-microbond.ps1" microbond-name

Microbond update with a proxy on macOS/Linux

On macOS/Linux use the following command to update a Microbond with a proxy:

/var/www/bzbond-server/bin/update-microbond.sh microbond-name http://proxy.address.com:port#

For example:

/var/www/bzbond-server/bin/update-microbond.sh microbond-name http://proxy.example.com:443

Microbond update with a proxy on Windows Server

On Windows Server use the following command to update a Microbond with a proxy:

powershell -File "C:\Program Files\bzBond-server\bin\update-microbond.ps1" microbond-name http://proxy.address.com:port#

For example:

powershell -File "C:\Program Files\bzBond-server\bin\update-microbond.ps1" microbond-name http://proxy.example.com:443

Microbond creation

Microbonds are npm packages. The quickest way to create one is using the create-microbond script.

Microbond creation on macOS/Linux

On macOS/Linux use the following command to create a Microbond:

bash <(curl -s https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/create-microbond.sh)

Microbond creation on Windows

On Windows use the following command to create a Microbond:

powershell -exec bypass -c "(New-Object Net.WebClient).Proxy.Credentials=[Net.CredentialCache]::DefaultNetworkCredentials;iwr('https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/create-microbond.ps1')|iex"

Microbond creation: Namespacing

It is strongly recommended that Microbond names and routes are namespaced to prevent collisions.

To illustrate, consider Beezwax-created Microbonds. These Microbonds and their routes are namespaced bzmb. The namespace is followed by a hyphen (-) and then a descriptive name. For example bzmb-array.

Routes within a Microbond must also adopt namespacing as duplicate routes are not allowed. For example a route to sort an array with bzmb-array would be named bzmb-array-sort.

Microbond publishing

Microbonds can be published by simply pushing the local git repo to github and making it public.

Microbonds that are private or otherwise unsuitable for publishing will need to be privately "published" (i.e. copied) to a location accessible to the server where they are being installed. See the installing Microbonds for examples of local repo references.

Microbond uninstallation

Microbond uninstallation on macOS/Linux

On macOS/Linux use the following command to uninstall a Microbond:

/var/www/bzbond-server/bin/uninstall-microbond.sh microbond-name

Microbond uninstallation on Windows Server

On Windows Server use the following command to uninstall a Microbond:

powershell -File "C:\Program Files\bzBond-server\bin\uninstall-microbond.ps1" microbond-name

Microbond uninstallation with a proxy on macOS/Linux

On macOS/Linux reference the proxy in the uninstallation command as follows:

/var/www/bzbond-server/bin/uninstall-microbond.sh -x http://proxy.address.com:port#

For example:

/var/www/bzbond-server/bin/uninstall-microbond.sh -x http://proxy.example.com:443

When uninstalling on macOS/Linux with command line arguments and a proxy either positional or named parameters must be used, they cannot be mixed.

Positional example:

/var/www/bzbond-server/bin/uninstall-microbond.sh microbond-name http://proxy.example.com:443

Named example:

/var/www/bzbond-server/bin/uninstall-microbond.sh -n microbond-name -x http://proxy.example.com:443

Mixed example (will not work):

/var/www/bzbond-server/bin/uninstall-microbond.sh microbond-name -x http://proxy.example.com:443

Microbond uninstallation with a proxy on Windows Server

On Windows Server reference the proxy in the uninstallation command as follows:

powershell -File "C:\Program Files\bzBond-server\bin\uninstall-microbond.ps1" -Name micrbond-name -Proxy http://proxy.address.com:port#

For example:

powershell -File "C:\Program Files\bzBond-server\bin\uninstall-microbond.ps1" -Name micrbond-name -Proxy http://proxy.example.com:443

Logs

bzBond-Server logs on macOS/Linux

On macOS/Linux the bzBond-server log folder is: /var/log/bzbond-server. There are two log files, error.log and access.log. The error.log file shows errors encountered during the execution of JavaScript code. The access.log file shows all calls to bzBond-server. It also logs when the bzBond-server service starts.

Viewing bzBond-Server logs on macOS

On macOS use the following command to view the most recent entries in the bzBond-server logs:

tail /var/log/bzbond-server/error.log

or

tail /var/log/bzbond-server/access.log

Viewing bzBond-Server logs on Linux

On Linux use the following command to view the bzBond-server log:

journalctl -u bzbond-server.service

Viewing bzBond-Server logs on Windows Server

On Windows Server logs for bzBond-server can be viewed in the Computer Management app in the following location:

Error Log:

C:\Program Files\bzBond-server\daemon\bzbondserver.err.log

Request log:

C:\Program Files\bzBond-server\daemon\bzbondserver.out.log

Uninstallation

Uninstallation on macOS/Linux

On macOS/Linux use the following command to uninstall bzBond-server:

curl -o- https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/uninstall.sh | bash

Uninstallation on Windows Server

On Windows Server use the following command to uninstall bzBond-server:

powershell Invoke-WebRequest https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/uninstall.ps1 -OutFile "$($env:USERPROFILE)\AppData\Local\Temp\uninstall.ps1"|powershell -File "$($env:USERPROFILE)\AppData\Local\Temp\uninstall.ps1"