Run Jitterbit App Builder on Docker

Introduction

You can run App Builder as a Docker container using the Jitterbit App Builder Docker image and a valid App Builder license.

Jitterbit's App Builder Docker image supports these databases:

Standard or Enterprise x64 editions of Microsoft SQL Server 2016 or later. This should be configured with collation sequence SQL_Latin1_General_CP1_CI_AS and mixed mode authentication.
MySQL 8.0 or later.
PostgreSQL 14 or later.

Important

While you should run an App Builder instance and its database separately on hosts that meet App Builder's system requirements, for the sake of simplicity, these instructions use the same host for both.

Prerequisites

You must have the following:

Docker engine installed and running.
Docker compose installed.
For the docker run example, an existing database is required. (The docker compose and additional examples include a service that runs an App Builder database, so do not require an existing one.)

Limitations

The following limitations apply to App Builder running as a Docker container. (They also apply to any Linux-based installations.)

Windows support

These Windows features are not supported:

Active Directory authentication
Crystal Reports
File system impersonation
Integrated Windows Authentication (IWA)
SAP ABAP
Third-party plugins

File upload size limit

File uploads are limited to 30,000,000 bytes (28.6 MB) by default. This is to help guard against Denial-of-Service (DoS) attacks.

To increase this limit, set the environment variable Kestrel__Limits__MaxRequestBodySize to the desired maximum file size in bytes.

Supported tags

The Docker image tags page shows which tags are available.

Valid tags consist of either 2 or 3 parts:

Tag parts	Description	Example
Major version number	Latest major series release	`4.0`
Major and minor version numbers	Latest major/minor series release	`4.44`
Major and minor version numbers with build number	Specific build for major/minor series release	`4.44.12345`

Important

For stability, you should use specific release (3-part) tags, and pin your App Builder instance to that build. To choose one, consult the release notes.

Start an App Builder instance with `docker run`

To start an App Builder instance that connects to an existing database running on the same host, follow these steps:

Create a file vinyl.env containing the following environment variables, with values substituted according to the table below:

ConnectionInfo__DatabaseType=<DB_TYPE>
ConnectionInfo__HostName=<DB_HOSTNAME>
ConnectionInfo__DatabaseName=<DB_NAME>
ConnectionInfo__Port=<DB_PORT>
ConnectionInfo__UserName=<DB_USERNAME>
ConnectionInfo__Password=<DB_PASSWORD>

Value	Replace with
`<DB_TYPE>`	Your database type, one of the following: `SQLServer`, `MySQL`, or `PostgreSql`.
`<DB_HOSTNAME>`	Your database server's hostname or IP address.
`<DB_PORT>`	(Optional) The port number your database service runs on. Defaults: `1433` (SQL Server), `3306` (MySQL), `5432` (PostgreSQL).
`<DB_NAME>`	(Optional) The App Builder database name. Default: `Vinyl`. For case-sensitive databases such as PostgreSQL and MySQL, `vinyl` is recommended to follow the database's name rules.
`<DB_USERNAME>`	The App Builder database username.
`<DB_PASSWORD>`	The App Builder database user's password.

(These and other environment variables are described in Configuring App Builder on startup.)

Example for PostgreSQL:

ConnectionInfo__DatabaseType=PostgreSql
ConnectionInfo__HostName=host.docker.internal
ConnectionInfo__DatabaseName=vinyl
ConnectionInfo__Port=5432
ConnectionInfo__UserName=postgres
ConnectionInfo__Password=postgres

Start the Docker container:

docker run --publish "80:8080" --env-file vinyl.env jitterbit/app-builder:4.45

Enter http://localhost in your browser's address bar and wait for the App Builder login page:
(Optional) Use your browser, curl, or a web API test tool to make a GET request on the container's health check endpoint http://localhost:80/ping. The response should be App Builder - OK - YYYY-mm-DDTHH:MM:SSZ, with the date and time expressed in ISO 8601 UTC form.
Log in with these credentials:
- Username: admin
- Password: P@55w0rd (The default App Builder administrator's password.)
On the Password Expired page, change the default password, then click the Save Password page:
On the Password Changed page, click the Continue button.
On the Active License page, click the Upload button:
On the License Upload page, click Browse to open your system's file browser. Find and open your App Builder license file, then click the Save button:
On the License Upload page, click the Activate button:
On the Active License page, click the Launch button:
The App Builder welcome page opens:

Start an App Builder instance and database with `docker compose`

The following examples use Docker Compose to start an App Builder instance and a Microsoft SQL Server database.

App Builder with Microsoft SQL Server

Follow these steps:

In an empty directory, create a file docker-compose.yml containing the following:

services:
  db:
    image: mcr.microsoft.com/mssql/server
    hostname: vinyldb
    environment:
      MSSQL_SA_PASSWORD: P@55w0rd
      ACCEPT_EULA: Y
    volumes:
      - ./db_data:/var/opt/mssql/data

  vinyl:
    depends_on:
      - db
    image: jitterbit/app-builder:4.0
    ports:
      - 80:8080
    volumes:
      - ./vinyl_data:/app/data
      - ./vinyl_logs:/app/logs
      - ./vinyl_keys:/app/keys
    environment:
      ConnectionInfo__DatabaseType: SQLServer
      ConnectionInfo__HostName: vinyldb
      ConnectionInfo__DatabaseName: vinyl
      ConnectionInfo__UserName: sa
      ConnectionInfo__Password: P@55w0rd

volumes:
  db_data:
  vinyl_data:
  vinyl_logs:
  vinyl_keys:

Start the services:
```
docker compose up -d
```
Check the log files in vinyl_logs, mounted onto the App Builder logs directory /app/logs. (The other mounts are /app/keys where encryption keys are stored, and /app/data, the data directory.)
Continue by following steps 3 to 12 from the previous section.

App Builder with MySQL

Follow the same steps as the example for Microsoft SQL Server, but replace the contents of the docker-compose.yml file with the following:

services:
  db:
    image: mysql
    hostname: vinyldb
    environment:
      MYSQL_ROOT_PASSWORD: P@55w0rd
    volumes:
      - db_data:/var/lib/mysql

  vinyl:
    depends_on:
      - db
    image: jitterbit/app-builder:4.0
    ports:
      - 80:8080
    volumes:
      - ./vinyl_data:/app/data
      - ./vinyl_logs:/app/log
      - ./vinyl_keys:/app/keys
    environment:
      ConnectionInfo__DatabaseType: MySQL
      ConnectionInfo__HostName: vinyldb
      ConnectionInfo__DatabaseName: vinyl
      ConnectionInfo__UserName: root
      ConnectionInfo__Password: P@55w0rd

volumes:
  db_data:
  vinyl_data:
  vinyl_logs:
  vinyl_keys:

App Builder with PostgreSQL