Run Vinyl on Docker¶

Introduction¶

This page shows how to run Vinyl as a Docker container using Jitterbit's Vinyl Docker image and a valid Vinyl license.

The Vinyl 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 a Vinyl instance and its database separately on hosts that meet Vinyl's hardware 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 a Vinyl 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 Vinyl version number with an optional build number (for example 3.3.34567). Tags without build numbers (3.3) are the most recent builds.

For stability, you should use tags with build numbers, and pin your Vinyl instance to that build. To choose one, consult the release notes.

Start a Vinyl Instance with `docker run`¶

To start a Vinyl 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) Vinyl database name. Default: `Vinyl`. This can be anything but must follow the database's name rules.
`<DB USERNAME>`	Vinyl database username.
`<DB PASSWORD>`	Vinyl database user's password.

(These and other environment variables are described in Configuring Vinyl 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 Vinyl 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 Vinyl - 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 Vinyl 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 Vinyl license file, then click Save:
On the License Upload page, click Activate:
On the Active License page, click Launch:
The Vinyl welcome page opens:

Start a Vinyl Instance and Database with `docker compose`¶

The following example uses Docker Compose to start a Vinyl 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: 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 Vinyl 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 Vinyl running as a Docker container, and to any Linux-based installations:

Support for Windows features varies depending on the Vinyl version:

Application	Supported on Vinyl 3.3+	Supported on Vinyl 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.

You can increase this limit on Vinyl version 3.2.31739 or later. To do so, set the environment variable Kestrel__Limits__MaxRequestBodySize to the desired maximum file size in bytes.

Additional `docker compose` Examples¶

Example docker-compose.yml for Vinyl 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 Vinyl 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: