BF Enterprise Documentation

Overview

FM BetterForms Enterprise is an extension of the FM BetterForms Cloud service allowing fully autonomous standalone operation.

Features

• Fully standalone serving of BF apps

• Apps are built with BF Cloud in the same manner as regular apps

• Apps can live both in the cloud and on-premise

• Choose which apps to host

Overview Diagram

Requirements

BF Enterprise runs out of a docker image and new BF Enterprise Helper file, therefore the requirements are:

• Docker Instance (Min 1);

• Env settings file;

• BF Enterprise Helper FileMaker File (will be provided);

• BF App migrated to the latest BF Editor (Environments version)

• FileMaker 19+.

Optional (not included with BF Enterprise docker image):

• Redis database for caching and increased performance/availability

• Redis database for messages (Sync between different servers, if more than one is being used);

• Redis database for OAuth if OAuth authentication is needed

Creating Redis server from Docker images

After installing Docker, as described below, a Redis database could be installed on the server as well.

Link to Redis’ official docs on how to run Redis Stack on Docker: https://redis.io/docs/stack/get-started/install/docker/

As a development environment, this Redis Stack instance can be deployed on localhost, and the env var REDIS_HOST will be host.docker.internal and a password won’t be needed.

Env File

Default environment variables to be declared in the file:

Key	Info	Required
FMS_CONNECTION_DB	FileMaker database name (Enterprise File)	Yes
FMS_CONNECTION_HOST	FileMaker host address	Yes
FMS_CONNECTION_USER	FileMaker username	Yes
FMS_CONNECTION_PASS	FileMaker password	Yes
AUTHENTICATION_SECRET	Salt used in authentication service	Yes
ENCRYPTION_KEY	Sal used to generate vaults	Yes
ISENTERPRISE	Set to enterprise mode (must be set as ISENTERPRISE=true)	Yes
FM_GATEWAY	XML or DAPI - gateway to be used to communicate with BF Enterprise Helper file (defaults to XML if no value is set)	No
NOW_DC	used to identify which server app is running from	No
REDIS_HOST	Redis host address for caching	No
REDIS_PASSWORD	Redis password for caching	No
REDIS_PORT	Redis port for caching	No
REDIS_HOST_MESSAGING	Redis host address for messaging	No
REDIS_PASSWORD_MESSAGING	Redis password for messaging	No
REDIS_PORT_MESSAGING	Redis port for messaging	No
REDIS_SECRET_MESSAGING	Redis secret for messaging	No
REDIS_HOST_OAUTH	Redis host address for OAuth	No
REDIS_PASSWORD_OAUTH	Redis password for OAuth	No
REDIS_PORT_OAUTH	Redis port for OAuth	No
REDIS_SECRET_OAUTH	Redis secret for OAuth	No

Here is a sample file (where values for the right hand side will be changed to your own info):

env .development_sample.development

Setting up the Server

Installation

Find the links to Docker’s official docs on how to install Docker on each OS.

Windows and MacOS only available for the Desktop version, whereas Linux has the option to use Engine (server) or Desktop.

• Linux

  • Desktop: https://docs.docker.com/desktop/linux/install/

  • Engine

  Distro	Link
  CentOS	https://docs.docker.com/engine/install/centos/
  Debian	https://docs.docker.com/engine/install/debian/
  Fedora	https://docs.docker.com/engine/install/fedora/
  RHEL	https://docs.docker.com/engine/install/rhel/
  SLES	https://docs.docker.com/engine/install/sles/
  Ubuntu	https://docs.docker.com/engine/install/ubuntu/
• Windows

  • Desktop: https://docs.docker.com/desktop/windows/install/

• MacOS

  • https://docs.docker.com/desktop/mac/install/

Loading image to a local repository

As of Jun 1st, 2022, the docker image is distributed via .tar file. In order to load this file to your local docker repository and be able to start the BF server, run the following docker command.

docker load -i bf-enterprise-v0-10-84.tar

Starting Server

Once server is setup and Docker installed in it, the following command can be used to start the service.

docker run -dp 80:80 --env-file yourEnvFile ourPublicRepo/betterforms:V0.10.84-bfe

• Where:

  • yourEnvFile: env file created according to previous section;

  • ourPublicRepo: repository where our docker image will be hosted.

Restarting Policies

When starting pods, different restart policies can be set for them:

• no - default option;

• on-failure;

• always;

• unless-stopped;

More information can be found on this link.

An example of how to start a new pod using a restart policy would be:

docker run -dp 80:80 --restart always --env-file yourEnvFile ourPublicRepo/betterforms:V0.10.84-bfe

Scaling up

Using the command above will start one pod, equivalent to one BF server. In order to increase availability and performance, more pods can be deployed in single or multiple servers. If multiple servers are being used, it will be necessary to use a load balancer in front of those servers to distribute load between multiple pods.

Hardware Recommendations

Minimum requirements for each pod are:

Resource	Value
Memory	200 MB
CPU	0.425 CPU

FM Credentials - Helper file

In order to enter the credentials that will be used to connect to your Helper file, you need to login into the enterprise file and use the UI to download the data from the cloud to your local enterprise file.

Once you have all records saved locally, you should have a connection record for each environment that was downloaded. Find the record that needs to be set the credentials in the Connections layout. The credentials will be added in the serverJSON field under the key vault, now make sure it’s under vault and not oauth.vault.

As shown in the image below, you should have a vault key with an empty object.

Untitled

Add your credentials as an object as follows.

{"username": "FM_USERNAME", "password": "FM_PASSWORD"}

If that still returns an error saying that “FileMaker Helper Credentials missing database name or user or password”, then add username and password to root path. In this case, the serverJSON object would look like

{
  "active": true,
  "apiKey": "BFAPI_XXXXXXX",
  "commonHookSetName": "app",
  "database": "BetterForms_Helper",
  "domains": ["your.app.domain"],
  "gateway": "DAPI",
  "hostAddress": "your.host.address",
  "id": "SV_YYYYYYY",
  "isDevMode": true,
  "oauth": {},
  "password": "YOUR-PASSWORD",
  "subDomain": "",
  "user": "BetterForms",
  "vault": {}
}

How it works

Development

All development is done in the cloud, in other words, we recommend that you have a development environment as part of your app that still has a domain pointing to it using BetterForm’s infrastructure (a .fmbetterforms.com domain could be used for this, for example). This will allow you to develop your app the same way as other apps. Once development is done and ready to deploy, then it can be deployed to the environment that will be downloaded to your on-premise enterprise file.

Downloading environment data

In order to download the environment to your local enterprise file:

1. Open your enterprise file and log into the enterprise app using your BetterForms credentials;

2. Select the organization that has the Enterprise subscription;

3. Choose the app;

4. Find the desired environment and click on Download.

Once the download is complete, Environments, Connections, SiteModel and Forms layouts should have new records added to them, and ready to serve your app from your on-premise enterprise file.