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.
- Installation
- Updating
- Restarting
- Usage
-
Microbonds
- Microbond installation
- Microbond update
- Microbond creation
- Microbond publishing
- Microbond uninstallation
- Logs
- Uninstallation
These installations assume a default installation of Claris/FileMaker Server on the specified platform.
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
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"
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
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
Sometimes for compatibility or testing reasons it is necessary to install a version of bzBond other than the latest.
On macOS/Linux reference the version tag you want to install in the installation command as follows:
curl -o- https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/install.sh | bash -s -- -v v#.#.#
For example:
curl -o- https://raw.githubusercontent.com/beezwax/bzBond/main/packages/bzBond-server/bin/install.sh | bash -s -- -v v0.9.47
On Windows Server reference the version tag you want to install 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" -Version v#.#.#
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" -Version v0.9.47
Use these instructions to update bzBond-server to the latest version
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
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"
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
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
Sometimes it might be necessary to manually restart the bzBond-server service
On macOS run the following commands to restart the bzBond-server service:
sudo launchctl unload /Library/LaunchDaemons/net.beezwax.bzbond-server.plist
sudo launchctl load /Library/LaunchDaemons/net.beezwax.bzbond-server.plist
On Linux run the following command to restart the bzBond-server service:
sudo systemctl restart bzbond-server
On Windows Server run the following command to restart the bzBond-server service:
Restart-Service -Name bzBond-server
For details on using bzBond-server see the bzBond-claris documentation for running JavaScript functions with the bzBondRelay script (client and server).
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.
On macOS/Linux use the following command to install a Microbond:
/var/www/bzbond-server/bin/install-microbond.sh
On Windows Server use the following command to install a Microbond:
powershell -File "C:\Program Files\bzBond-server\bin\install-microbond.ps1"
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.
/var/www/bzbond-server/bin/install-microbond.sh bzmb-hello-world https://github.com/beezwax/bzbond-server-microbond-example
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.
/home/my-username/a-microbond-git-repo
../some-folder/a-microbond-git-repo
C:\Users\my-username\a-microbond-git-repo
..\some-folder\a-microbond-git-repo
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
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
On macOS/Linux use the following command to update a Microbond:
/var/www/bzbond-server/bin/update-microbond.sh microbond-name
On Windows Server use the following command to update a Microbond:
powershell -File "C:\Program Files\bzBond-server\bin\update-microbond.ps1" microbond-name
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
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
Microbonds are npm packages. The quickest way to create one is using the create-microbond script.
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)
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"
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.
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.
On macOS/Linux use the following command to uninstall a Microbond:
/var/www/bzbond-server/bin/uninstall-microbond.sh microbond-name
On Windows Server use the following command to uninstall a Microbond:
powershell -File "C:\Program Files\bzBond-server\bin\uninstall-microbond.ps1" microbond-name
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
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
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.
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
On Linux use the following command to view the bzBond-server log:
journalctl -u bzbond-server.service
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
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
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"