large_v-transUsing Applications with Docker

With unRAID 6, we can now run any Linux application on unRAID, regardless of the distribution format.  That means whether an app was written for Ubuntu, CentOS, Arch, Red Hat, or any other variant, unRAID can run it.  This is accomplished through the use of Docker Containers, which allow us to provide each application with it’s own isolated operating environment in which it cannot create software compatibility or coexistance conflicts with other applications.  This guide will show you how to get started with Docker on unRAID 6 to install media servers, file sharing software, backup solutions, gaming servers, and much more.

Prerequisites

  • A system up and running with unRAID 6.0 and are connected via a web browser to the unRAID webGui (e.g., “http://tower” or “http://tower.local” from Mac by default).
  • A share created called “appdata” that will be used to store application metadata.

Applications are made available and supported by both the Docker and unRAID user communities respectively.

Creating Your Docker Virtual Disk

The first step on your Docker journey will be to create your Docker virtual disk image where the service and all the application images will live.

  • Open a web browser on your Mac or PC and navigate to the unRAID webGui.
  • Click on the Docker tab at the top of the screen.
  • Set Enable Docker to Yes.
  • Specify an initial virtual disk image size (it is recommended that beginners start with at least a 10GB image size).  This can be enlarged later, but can never be reduced in size once set.
  • Pick a location for your Docker virtual disk.
    • The path must be device-specific (you cannot specify a path through the user share file system; e.g., “/mnt/user/docker.img” is not a valid path).
    • It is recommended to store the virtual disk on the root of the cache disk or on the root of a data disk if no cache disk is available.
  • Click Apply to create the virtual disk and start the Docker service (this may take some time).

dockerguide-creating-virtual-disk

Adding Template Repositories

Once the service has started, the web page will refresh and a new “Docker Containers” section will appear.  The easiest way to add Dockerized applications to unRAID is through the use of template repositories which act as a catalog for installing and configuring applications with ease through the unRAID web interface.  These templates and their respective applications are maintained by the unRAID user community.

  • Check out the complete list of available applications and repositories in our community forums.
  • For each repository you want to add, copy the link of the repository and paste it into the “Template repositories” field on the Docker Settings page.
  • Separate multiple entries in the list by pressing Enter on your keyboard.
  • When you’re done adding repositories, click the Save button.

dockerguide-adding-template-repos

Creating Your First Application Container

With your template repositories added, you can now begin creating application “Containers” using Docker.  Containers prevent software from causing conflicts with other applications and services running on unRAID.

  • Click Add Container on the Docker Containers page to begin adding your first application.
  • Now click the Template drop down to select an application from one of the repositories we added previously.
  • After selecting, the page will refresh and new fields will be presented for configuring the container’s network and storage access.
  • Be sure to read the Description section for any special instructions.

dockerguide-select-application-template

Network Type

If the Bridge type is selected, the application’s network access will be restricted to only communicating on the ports specified in the port mappings section.  If the Host type is selected, the application will be given access to communicate using any port on the host that isn’t already mapped to another in-use application/service.  Generally speaking, it is recommended to leave this setting to its default value as specified per application template.

Volume Mappings

Applications can be given read and write access to your data by mapping a directory path from the container to a directory path on the host.  When looking at the volume mappings section, the Container volume represents the path from the container that will be mapped.  The Host path represents the path the Container volume will map to on your unRAID system.  All applications should require at least one volume mapping to store application metadata (e.g., media libraries, application settings, user profile data, etc.).  Clicking inside these fields provides a “picker” that will let you navigate to where the mapping should point.  Additional mappings can be manually created by clicking the Add Path button.  Most applications will need you to specify additional mappings in order for the application to interact with other data on the system (e.g., with Plex Media Server, you should specify an additional mapping to give it access to your media files).  It is important that when naming Container volumes that you specify a path that won’t conflict with already existing folders present in the container.  If unfamiliar with Linux, using a prefix such as “unraid_” for the volume name is a safe bet (e.g., “/unraid_media” is a valid Container volume name).

Port Mappings

When the network type is set to Bridge, you will be given the option of customizing what ports the container will use.  While applications may be configured to talk to a specific port by default, we can remap those to different ports on our host with Docker.  This means that while three different apps may all want to use port 8000, we can map each app to a unique port on the host (e.g., 8000, 8001, and 8002).  When the network type is set to Host, the container will be allowed to use any available port on your system.  Additional port mappings can be created, similar to Volumes, although this is not typically necessary when working with templates as port mappings should already be specified.

IMPORTANT NOTE:  If adjusting port mappings, do not modify the settings for the Container port as only the Host port can be adjusted.

dockerguide-ports

Create

With your volume and port mappings configured, you are now ready to create your first Docker container.  Click the Create button and the download process will begin.

dockerguide-createcont1

A few things worth noting while the image is downloading:

  • After clicking Create, do not close your browser window or attempt to navigate to other tabs using the browser until the download is complete.
  • Initial downloads per template repository may take longer than subsequent downloads per repository.
  • When the download process completes, you can click the Done button to return to the Docker page and continue adding applications.

dockerguide-createcont2

Controlling Your Application

dockerguide-controllingOnce the download is complete, the application is started automatically.  To interact with your application, we begin by clicking on the icon visible on the Docker page of the unRAID web interface.  Doing so will make a context menu appear with multiple options:

  • WebUI
    • Most apps added through Docker will have a web interface that you can access to configure and use them, but not all.
    • Clicking this option will launch a new browser tab/window directly to the applications web interface.
    • For apps that do NOT have a web interface, read the description when adding the container for instructions on how to make use of the app once it’s running.
  • Update
    • This option only appears after clicking Check for Updates (if available).
  • Start/Stop
    • This will toggle the active state of the container.
  • Logs
    • If you are having difficulties with your application, useful information may be present the application’s log.
    • Logs for applications are stored separately from unRAID’s system log itself.
  • Edit
    • Container settings such as port and volume mappings can be changed by clicking this option.
    • Once changes are applied, the container will start automatically, even if it is stopped initially.
  • Enable/Disable autostart
    • Toggling this will change the default behavior of the application when the Docker service is started.
  • Remove
    • Allows you to remove either the entire application, or just the container.
    • Removing a container without it’s “image” will make adding the application again later a much faster process (as it will not need to be redownloaded).

Using Volume Mappings From Inside a Container

One of the first things you will do after your application is running will be to configure it.  Configuration typically will involve specifying storage locations from within the applications web interface.  When doing so, remember to look for the volume mappings you defined when adding your container.  For example, if I needed to specify a folder path in the BT Sync app that would point to my Media share, I would specify the path of “/unraid_media” in the applications interface, as depicted below.

dockerguide-usingvolumes

Other Tips and Tricks

Using Docker containers to run applications on unRAID is incredibly easy and very powerful.  Here are some additional tips to improve your experience:

  • Using a cache device for storing your Docker virtual disk image and application data can improve performance.
  • Run multiple instances of the same app at the same time, which is useful for testing out alternate versions before upgrading.
  • Click the Advanced View toggle on the top right when viewing the Docker page or adding applications to see additional configuration options.
  • Learn more about Docker containers from our helpful user community.
Back to Top