This project provides a Docker container for MakeMKV.

The graphical user interface (GUI) of the application can be accessed through a modern web browser, requiring no installation or configuration on the client side, or via any VNC client.

A fully automated mode is also available: insert a DVD or Blu-ray disc into an optical drive and let MakeMKV rips it without any user interaction.

MakeMKV is your one-click solution to convert video that you own into free and patents-unencumbered format that can be played everywhere. MakeMKV is a format converter, otherwise called "transcoder". It converts the video clips from proprietary (and usually encrypted) disc into a set of MKV files, preserving most information but not changing it in any way. The MKV format can store multiple video/audio tracks with all meta-information and preserve chapters.

• Quick Start
• Usage
  • Environment Variables
    • Deployment Considerations
  • Data Volumes
  • Ports
  • Changing Parameters of a Running Container
  • Docker Compose File
• Docker Image Versioning and Tags
• Docker Image Update
  • Synology
  • unRAID
• User/Group IDs
• Accessing the GUI
• Security
  • SSVNC
  • Certificates
  • VNC Password
  • Web Authentication
    • Configuring Users Credentials
• Reverse Proxy
  • Routing Based on Hostname
  • Routing Based on URL Path
  • Web Audio
  • Web File Manager
• Shell Access
• Access to Optical Drives
• Automatic Disc Ripper
• Hooks
• Troubleshooting
  • Expired Beta Key
• Support or Contact

Launch the MakeMKV docker container with the following command:

docker run -d \
    --name=makemkv \
    -p 5800:5800 \
    -v /docker/appdata/makemkv:/config:rw \
    -v /home/user:/storage:ro \
    -v /home/user/MakeMKV/output:/output:rw \
    --device /dev/sr0 \
    --device /dev/sg2 \
    jlesage/makemkv

Where:

• /docker/appdata/makemkv: Stores the application's configuration, state, logs, and any files requiring persistency.
• /home/user: Contains files from the host that need to be accessible to the application.
• /home/user/MakeMKV/output: This is where extracted videos are written.
• /dev/sr0: First linux device file corresponding to the optical drive.
• /dev/sg2: Second linux device file corresponding to the optical drive.

Access the MakeMKV GUI by browsing to http://your-host-ip:5800. Files from the host appear under the /storage folder in the container.

docker run [-d] \
    --name=makemkv \
    [-e <VARIABLE_NAME>=<VALUE>]... \
    [-v <HOST_DIR>:<CONTAINER_DIR>[:PERMISSIONS]]... \
    [-p <HOST_PORT>:<CONTAINER_PORT>]... \
    jlesage/makemkv

To customize the container's behavior, you can pass environment variables using the -e parameter in the format <VARIABLE_NAME>=<VALUE>.

Many tools used to manage Docker containers extract environment variables defined by the Docker image to create or deploy the container.

For example, this behavior is seen in:

• The Docker application on Synology NAS
• The Container Station on QNAP NAS
• Portainer
• etc.

While this is useful for users to adjust environment variable values to suit their needs, keeping all of them can be confusing and even risky.

A good practice is to set or retain only the variables necessary for the container to function as desired in your setup. If a variable is left at its default value, it can be removed. Keep in mind that all environment variables are optional; none are required for the container to start.

Removing unneeded environment variables offers several benefits:

• Prevents retaining variables no longer used by the container. Over time, with image updates, some variables may become obsolete.
• Allows the Docker image to update or fix default values. With image updates, default values may change to address issues or support new features.
• Avoids changes to variables that could disrupt the container's functionality. Some undocumented variables, like PATH or ENV, are required but not meant to be modified by users, yet container management tools may expose them.
• Addresses a bug in Container Station on QNAP and the Docker application on Synology, where variables without values may not be allowed. This behavior is incorrect, as variables without values are valid. Removing unneeded variables prevents deployment issues on these devices.

The following table describes the data volumes used by the container. Volume mappings are set using the -v parameter with a value in the format <HOST_DIR>:<CONTAINER_DIR>[:PERMISSIONS].

The following table lists the ports used by the container.

When using the default bridge network, ports can be mapped to the host using the -p parameter with value in the format <HOST_PORT>:<CONTAINER_PORT>. The internal container port may not be changeable, but you can use any port on the host side.

See the Docker Docker Container Networking documentation for details.

Environment variables, volume mappings, and port mappings are specified when creating the container. To modify these parameters for an existing container, follow these steps:

1. Stop the container (if it is running):

docker stop makemkv

2. Remove the container:

docker rm makemkv

3. Recreate and start the container using the docker run command, adjusting parameters as needed.

Below is an example docker-compose.yml file for use with Docker Compose.

Adjust the configuration to suit your needs. Only mandatory settings are included in this example.

version: '3'
services:
  makemkv:
    image: jlesage/makemkv
    ports:
      - "5800:5800"
    volumes:
      - "/docker/appdata/makemkv:/config:rw"
      - "/home/user:/storage:ro"
      - "/home/user/MakeMKV/output:/output:rw"
    devices:
      - "/dev/sr0:/dev/sr0"
      - "/dev/sg2:/dev/sg2"

Each release of a Docker image is versioned, and each version as its own image tag. Before October 2022, the versioning scheme followed semantic versioning.

Since then, the versioning scheme has shifted to calendar versioning with the format YY.MM.SEQUENCE, where:

• YY is the zero-padded year (relative to year 2000).
• MM is the zero-padded month.
• SEQUENCE is the incremental release number within the month (first release is 1, second is 2, etc).

View all available tags on Docker Hub or check the Releases page for version details.

The Docker image is regularly updated to incorporate new features, fix issues, or integrate newer versions of the containerized application. Several methods can be used to update the Docker image.

If your system provides a built-in method for updating containers, this should be your primary approach.

Alternatively, you can use Watchtower, a container-based solution for automating Docker image updates. Watchtower seamlessly handles updates when a new image is available.

To manually update the Docker image, follow these steps:

1. Fetch the latest image:

docker pull jlesage/makemkv

2. Stop the container:

docker stop makemkv

3. Remove the container:

docker rm makemkv

4. Recreate and start the container using the docker run command, with the same parameters used during initial deployment.

For Synology NAS users, follow these steps to update a container image:

1. Open the Docker application.
2. Click Registry in the left pane.
3. In the search bar, type the name of the container (jlesage/makemkv).
4. Select the image, click Download, and choose the latest tag.
5. Wait for the download to complete. A notification will appear once done.
6. Click Container in the left pane.
7. Select your MakeMKV container.
8. Stop it by clicking Action -> Stop.
9. Clear the container by clicking Action -> Reset (or Action -> Clear if you don't have the latest Docker application). This removes the container while keeping its configuration.
10. Start the container again by clicking Action -> Start. NOTE: The container may temporarily disappear from the list while it is recreated.

For unRAID users, update a container image with these steps:

1. Select the Docker tab.
2. Click the Check for Updates button at the bottom of the page.
3. Click the apply update link of the container to be updated.

When mapping data volumes (using the -v flag of the docker run command), permission issues may arise between the host and the container. Files and folders in a data volume are owned by a user, which may differ from the user running the application. Depending on permissions, this could prevent the container from accessing the shared volume.

To avoid this, specify the user the application should run as using the USER_ID and GROUP_ID environment variables.

To find the appropriate IDs, run the following command on the host for the user owning the data volume:

id <username>

This produces output like:

uid=1000(myuser) gid=1000(myuser) groups=1000(myuser),4(adm),24(cdrom),27(sudo),46(plugdev),113(lpadmin)

Use the uid (user ID) and gid (group ID) values to configure the container.

Assuming the container's ports are mapped to the same host's ports, access the application's GUI as follows:

• Via a web browser:

http://<HOST_IP_ADDR>:5800

• Via any VNC client:

<HOST_IP_ADDR>:5900

By default, access to the application's GUI uses an unencrypted connection (HTTP or VNC).

A secure connection can be enabled via the SECURE_CONNECTION environment variable. See the Environment Variables section for details on configuring environment variables.

When enabled, the GUI is accessed over HTTPS when using a browser, with all HTTP accesses redirected to HTTPS.

For VNC clients, the connection can be secured using on of two methods, configured via the SECURE_CONNECTION_VNC_METHOD environment variable:

• SSL: An SSL tunnel is used to transport the VNC connection. Few VNC clients supports this method; SSVNC is one that does.
• TLS: A VNC security type negotiated during the VNC handshake. It uses TLS to establish a secure connection. Clients may optionally validate the server’s certificate. Valid certificates must be provided for this validation to succeed. See Certificates for details. TigerVNC is a client that supports TLS encryption.

SSVNC is a VNC viewer that adds encryption to VNC connections by using an SSL tunnel to transport the VNC traffic.

While the Linux version of SSVNC works well, the Windows version has issues. At the time of writing, the latest version 1.0.30 fails with the error:

ReadExact: Socket error while reading

For convenience, an unofficial, working version is provided here:

https://github.com/jlesage/docker-baseimage-gui/raw/master/tools/ssvnc_windows_only-1.0.30-r1.zip

This version upgrades the bundled stunnel to version 5.49, resolving the connection issues.

The following certificate files are required by the container. If missing, self-signed certificates are generated and used. All files are PEM-encoded x509 certificates.

To restrict access to your application, set a password using one of two methods:

• Via the VNC_PASSWORD environment variable.
• Via a .vncpass_clear file at the root of the /config volume, containing the password in clear text. During container startup, the content is obfuscated and moved to .vncpass.

The security of the VNC password depends on:

• The communication channel (encrypted or unencrypted).
• The security of host access.

When using a VNC password, enable a secure connection to prevent sending the password in clear text over an unencrypted channel.

Unauthorized users with sufficient host privileges can retrieve the password by:

• Viewing the VNC_PASSWORD environment variable via docker inspect. By default, the docker command requires root access, but it can be configured to allow users in a specific group.
• Decrypting the /config/.vncpass file, which requires root or USER_ID permissions.

Access to the application's GUI via a web browser can be protected with a login page. When enabled, users must provide valid credentials to gain access.

Enable web authentication by setting the WEB_AUTHENTICATION environment variable to 1. See the Environment Variables section for details on configuring environment variables.

User credentials can be configured in two ways:

1. Via container environment variables.
2. Via a password database.

Container environment variables provide a quick way to configure a single user. Set the username and password using:

• WEB_AUTHENTICATION_USERNAME
• WEB_AUTHENTICATION_PASSWORD

See the Environment Variables section for details on configuring environment variables.

For a more secure method or to configure multiple users, use a password database at /config/webauth-htpasswd within the container. This file uses the Apache HTTP server's htpasswd format, storing bcrypt-hashed passwords.

Manage users with the webauth-user tool:

• Add a user: docker exec -ti <container name> webauth-user add <username>
• Update a user: docker exec -ti <container name> webauth-user update <username>
• Remove a user: docker exec <container name> webauth-user del <username>
• List users: docker exec <container name> webauth-user list

The following sections provide NGINX configurations for setting up a reverse proxy to this container.

A reverse proxy server can route HTTP requests based on the hostname or URL path.

In this scenario, each hostname is routed to a different application or container.

For example, if the reverse proxy server runs on the same machine as this container, it would proxy all HTTP requests for makemkv.domain.tld to the container at 127.0.0.1:5800.

Here are the relevant configuration elements to add to the NGINX configuration:

map $http_upgrade $connection_upgrade {
	default upgrade;
	''      close;
}

upstream docker-makemkv {
	# If the reverse proxy server is not running on the same machine as the
	# Docker container, use the IP of the Docker host here.
	# Make sure to adjust the port according to how port 5800 of the
	# container has been mapped on the host.
	server 127.0.0.1:5800;
}

server {
	[...]

	server_name makemkv.domain.tld;

	location / {
	        proxy_pass http://docker-makemkv;
	}

	location /websockify {
		proxy_pass http://docker-makemkv;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection $connection_upgrade;
		proxy_read_timeout 86400;
	}

	# Needed when audio support is enabled.
	location /websockify-audio {
		proxy_pass http://docker-makemkv;
		proxy_http_version 1.1;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection $connection_upgrade;
		proxy_read_timeout 86400;
	}
}

In this scenario, the same hostname is used, but different URL paths route to different applications or containers. For example, if the reverse proxy server runs on the same machine as this container, it would proxy all HTTP requests for server.domain.tld/filebot to the container at 127.0.0.1:5800.

Here are the relevant configuration elements to add to the NGINX configuration:

map $http_upgrade $connection_upgrade {
	default upgrade;
	''      close;
}

upstream docker-makemkv {
	# If the reverse proxy server is not running on the same machine as the
	# Docker container, use the IP of the Docker host here.
	# Make sure to adjust the port according to how port 5800 of the
	# container has been mapped on the host.
	server 127.0.0.1:5800;
}

server {
	[...]

	location = /makemkv {return 301 $scheme://$http_host/makemkv/;}
	location /makemkv/ {
		proxy_pass http://docker-makemkv/;
		# Uncomment the following line if your Nginx server runs on a port that
		# differs from the one seen by external clients.
		#port_in_redirect off;
		location /makemkv/websockify {
			proxy_pass http://docker-makemkv/websockify;
			proxy_http_version 1.1;
			proxy_set_header Upgrade $http_upgrade;
			proxy_set_header Connection $connection_upgrade;
			proxy_read_timeout 86400;
		}
		# Needed when audio support is enabled.
		location /makemkv/websockify-audio {
			proxy_pass http://docker-makemkv/websockify-audio;
			proxy_http_version 1.1;
			proxy_set_header Upgrade $http_upgrade;
			proxy_set_header Connection $connection_upgrade;
			proxy_read_timeout 86400;
		}
	}
}

The container supports streaming audio from the application, played through the user's web browser. Audio is not supported for VNC clients.

Audio is streamed with the following specification:

• Raw PCM format
• 2 channels
• 16-bit sample depth
• 44.1kHz sample rate

Enable web audio by setting WEB_AUDIO to 1. See the Environment Variables section for details on configuring environment variables.

The container includes a simple file manager for interacting with container files through a web browser, supporting operations like renaming, deleting, uploading, and downloading.

Enable the file manager by setting WEB_FILE_MANAGER to 1. See the Environment Variables section for details on configuring environment variables.

By default, the container's entire filesystem is not accessible. The WEB_FILE_MANAGER_ALLOWED_PATHS environment variable is a comma-separated list that specifies which paths within the container are allowed to be accessed. When set to AUTO (the default), it automatically includes commonly used folders and any folders mapped to the container.

The WEB_FILE_MANAGER_DENIED_PATHS environment variable defines which paths are explicitly denied access by the file manager. A denied path takes precedence over an allowed one.

To access the shell of a running container, execute the following command:

docker exec -ti CONTAINER sh

Where CONTAINER is the ID or the name of the container used during its creation.

By default, a Docker container does not have access to host's devices. However, access to one or more devices can be granted with the --device DEV parameter of the docker run command.

In Linux, optical drives are represented by two device files named /dev/srX and /dev/sgY, where X and Y are numbers (e.g., /dev/sr0, /dev/sg0 for the first drive, /dev/sr1, /dev/srg1 for the second, etc). To allow MakeMKV to access the first drive, use this parameter:

--device /dev/sr0 --device /dev/sg1

To identify the correct Linux devices to expose, check the container's log during startup. Look for messages like:

[cont-init   ] 54-check-optical-drive.sh: looking for usable optical drives...
[cont-init   ] 54-check-optical-drive.sh: found optical drive 'hp HLDS DVDRW GUD1N LD02' [/dev/sr0, /dev/sg3]
[cont-init   ] 54-check-optical-drive.sh:   [ OK ]   associated SCSI Generic (sg) device detected: /dev/sg3.
[cont-init   ] 54-check-optical-drive.sh:   [ ERR ]  the host device /dev/sg3 is not exposed to the container.
[cont-init   ] 54-check-optical-drive.sh:   [ OK ]   associated SCSI CD-ROM (sr) device detected: /dev/sr0.
[cont-init   ] 54-check-optical-drive.sh:   [ WARN ] the host device /dev/sr0 is not exposed to the container.
[cont-init   ] 54-check-optical-drive.sh:            performance or ability to use the device will suffer.
[cont-init   ] 54-check-optical-drive.sh: no usable optical drives found.

This indicates that /dev/sr0 and /dev/sg3 need to be exposed to the container.

Alternatively, identify Linux devices from the host by running:

lsscsi -g

The output's last two columns for an optical drive indicate the devices to expose. The following example shows that /dev/sr0 and /dev/sg3 should be exposed:

[0:0:0:0]    disk    ATA      TOSHIBA DT01ACA0 A800  /dev/sda   /dev/sg0
[1:0:0:0]    disk    ATA      ST3500418AS      HP34  /dev/sdb   /dev/sg1
[2:0:0:0]    disk    ATA      WDC WD6401AALS-0 3B01  /dev/sdc   /dev/sg2
[4:0:0:0]    cd/dvd  hp HLDS  DVDRW  GUD1N     LD02  /dev/sr0   /dev/sg3

This container includes an automatic disc ripper. When enabled, any DVD or Blu-ray video disc inserted into an optical drive is automatically ripped. MakeMKV decrypts and extracts all titles (e.g. main movie, bonus features) into MKV files.

Enable the automatic disc ripper by setting the environment variable AUTO_DISC_RIPPER to 1.

To eject the disc when ripping completes, set the environment variable AUTO_DISC_RIPPER_EJECT to 1.

If multiple drives are available, simultaneous ripping is supported by setting the environment variable AUTO_DISC_RIPPER_PARALLEL_RIP to 1.

See the Environment Variables for details on configuring environment variables.

Custom actions can be performed at various disc-ripping stages using hooks. Hooks are shell scripts executed by both the MakeMKV GUI and the automatic disc ripper.

Hooks are optional. By default, none are defined. A hook is executed when a script exists at a specific path.

The table below lists all supported hooks:

If the beta key has expired, simply restart the container. It will automatically fetch and install the latest key (if available).

Having troubles with the container or have questions? Please create a new issue.

For other Dockerized applications, visit https://jlesage.github.io/docker-apps.