Run Jitterbit App Builder on Docker

Introduction

This page shows how to run App Builder as a Docker container using Jitterbit App Builder Docker image and a valid App Builder license.

The App Builder Docker image has support for 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 one host for both.

Before you start, you must have a Docker engine and Docker compose installed, and be aware of the limitations. 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.

Supported tags

The Docker image tags page shows which tags are available.

Tags are made of the App Builder version number with an optional build number (for example 4.0.12345). Tags without build numbers (4.0) are the most recent builds.

For stability, you should use tags with build numbers, 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>`	One of `SQLServer`, `MySQL`, or `PostgreSql`.
`<DB HOSTNAME>`	Database server's hostname or IP address.
`<DB PORT>`	(Optional) Port number the database service runs on. Default: `1433` (SQL Server), `3306` (MySQL), `5432` (PostgreSQL).
`<DB NAME>`	(Optional) App Builder database name. Default: `App Builder`. This can be anything but must follow the database's name rules.
`<DB USERNAME>`	App Builder database username.
`<DB PASSWORD>`	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:80" --env-file vinyl.env jitterbit/vinyl:3.3

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 Save Password:
On the Password Changed page, click Continue.
On the Active License page, click Upload:
On the License Upload page, click Browse to open your system's file browser. Find and open your App Builder license file, then click Save:
On the License Upload page, click Activate:
On the Active License page, click Launch:
The App Builder welcome page opens:

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

The following example uses Docker Compose to start an App Builder instance and a Microsoft SQL Server database (more examples below):

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

version: "3"

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/vinyl:3.3
    ports:
      - 80:80
    volumes:
      - ./vinyl_data:/app/data
      - ./vinyl_logs:/app/logs
      - ./vinyl_keys:/app/keys
    environment:
      ConnectionInfo__DatabaseType: SQLServer
      ConnectionInfo__HostName: vinyldb
      ConnectionInfo__DatabaseName: App Builder
      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.

Limitations

The following limitations apply to App Builder running as a Docker container, and to any Linux-based installations:

Support for Windows features varies depending on the App Builder version:

Application	Supported on App Builder 3.3+	Supported on App Builder 3.2
IBM DB2 for i
Salesforce Platform1
Active Directory authentication
Crystal Reports
File system impersonation
Integrated Windows Authentication (IWA)
SAP ABAP
Third-party plugins

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.

Additional `docker compose`Examples

Example docker-compose.yml for App Builder using MySQL as the backend database:

version: '3.0'

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

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

volumes:
  db_data:
  vinyl_data:
  vinyl_logs:
  vinyl_keys:

Example docker-compose.yml for App Builder using PostgreSQL as the backend database:

version: "3"

services:
  db:
    image: postgres
    hostname: vinyldb
    environment:
      POSTGRES_PASSWORD: postgres
    volumes:
      - db_data: /var/lib/postgresql/data

  vinyl:
    depends_on:
      - db
    image: jitterbit/vinyl:3.3
    ports:
      - 80:80
    volumes:
      - ./vinyl_data:/app/data
      - ./vinyl_logs:/app/logs
      - ./vinyl_keys:/app/keys
    environment:
      ConnectionInfo__DatabaseType: PostgreSql
      ConnectionInfo__HostName: vinyldb
      ConnectionInfo__UserName: postgres
      ConnectionInfo__Password: postgres

volumes:
  db_data:
  vinyl_data:
  vinyl_logs:
  vinyl_keys: