Skip to content Skip to sidebar Skip to footer

Dynamics 365 Business Central Blog

Buy Me a Coffee
Menu
Buy Me a Coffee
Buy Me a Coffee
Environment Administration

How to run BC in a Docker container

1Comment41 minRead time
Share this article
Share Post

Introduction

If you want to test the latest (or even upcoming) version of BC on your own in terms of core functionalities (Base Application or System Application), if you want to set up your own local development environment for your own purposes (e.g., learning to program in AL) or for projects you are involved in, or if you simply need to check specific system behavior (standard or using a specific dedicated PTE or ISV extension) on the same version as the customer (matched with the build number) because, for some reason, you can’t do it on the production environment on a copied company, test database, or sandbox… running a Docker container with BC on board is just for you. In this step-by-step guide, you’ll show you how to do it.

What are Containers?

The Business Central application needs an installed SQL Server database, IIS web server, BC application server, and additional components to operate. If you wanted to install all of this on your own computer (just for the purpose of checking something in BC), your computer would quickly lose its performance and would no longer be a reliable daily work tool. The installed server components would quickly consume your computer’s resources, and the operating system itself would be heavily loaded.

Containers are one the best ways to install and run applications on a computer, while isolating them (and all required components) from the operating system. By installing the entire BC in a so-called container, we keep all installation components in one isolated place (in the container!) giving us complete control over it. The content of the container will not touch our system registry, nor will it consume more hardware resources than we allow it to.

And what is Docker then?

Docker, specifically Docker Engine, is a client-server application that enables the creation of containers on our computer, controls them, and allows us to manage them.

Ways to create a BC test environment

I briefly described what containers are above. If you want to learn more, a broader description can be found in the article Ways to create a BC test environment, where I described various ways to create environments for testing or demonstration purposes. It’s worth reading to better understand the concept of containerized applications, know the advantages of containerization over virtual machines, be aware of the possibilities, limitations, and make sure that a BC container is exactly what you need.

System requirements

Before we move on to running your first container with BC, you need to verify if your computer and operating system meet the requirements for running Windows containers with the Docker Desktop application.

  • 64-bit operating system Windows 10 or Windows 11 in Professional or Enterprise edition – unfortunately, the Home edition is not suitable as it supports Linux containers only, while BC requires support for Windows containers,
  • Enabled optional Windows features: Hyper-V and Containers,
  • 64-bit processor with hardware virtualization support and Second Level Address Translation (SLAT) ↗,
  • At least 4 GB of RAM (of course, more is recommended),
  • Enabled hardware virtualization in the computer’s BIOS.

While the requirements over operating system version, processor type, and amount of RAM is rather obvious, below I describe how to enable the appropriate optional Windows features and how to check if hardware virtualization is enabled, and if not, what to look for in the computer’s BIOS to enable virtualization.

Windows Features
  1. To open the Windows Features window, press the ⊞ Win + R key combination or right-click on the Start menu → Run, then in the Run window type optionalfeatures and press Enter or the OK button.
  2. In the Windows Features window, find the Hyper-V entry in the list and make sure it is enabled (if not, enable it), then find the Containers entry in the list and also make sure it is enabled (if not, enable it).
  3. Confirm the changes with the OK button. If any feature was disabled, the system will install it at this time, which may take a few minutes. A system restart is recommended after installation.
Hardware virtualization

First, check if hardware virtualization is already enabled:

  1. Open Task Manager by right-clicking on the taskbar → Task Manager or right-clicking on the Start menu → Task Manager or the classic way: press the Ctrl + Alt + del key combination and select Task Manager.
  2. In the Task Manager window, go to the Performance section and click on CPU. Below the processor usage charts, there should be information about enabled virtualization: Virtualization: Enabled.

If hardware virtualization is disabled, you need to enable it from the BIOS. The steps required differ for each computer manufacturer, but usually, you need to enter the BIOS settings during computer booting procedure and look for an option called Virtualization Technology (VTx) or something similar and set its value to enabled.

Step 1: Install Docker Desktop

  1. Go to: www.docker.com/products/docker-desktop ↗, download the Docker Desktop for Windows application and install it.
  2. After a successful installation, the Docker Desktop icon should appear in the system tray (next to the clock).
  3. Switch the application to support Windows containers: right-click on the Docker Desktop icon in the system tray and select Switch to Windows containers.
Switching the Docker Desktop application to support Windows containers

Step 2: Install BcContainerHelper

Although the Docker Desktop application has a GUI, it is mainly used to manage existing containers. Most operations needed to create a container are done using PowerShell commands. While you can use the standard Docker module for PowerShell and the standard commands it contains, installing the BcContainerHelper module and using its commands will be a huge convenience when creating and managing containers specifically for Business Central.

Briefly about BcContainerHelper

BcContainerHelper (GitHub repository ↗) is a PowerShell module created by Microsoft (developed since its first release by Freddy Kristiansen ↗), which makes it easy to work with Business Central or NAV containers on Docker.

BcContainerHelper does part of the work for us, accumulates many individual tasks into one, has a built-in wizard for creating a container with BC, makes it easy to create a container with a chosen version of BC or NAV (even down to the build number), and also facilitates operations (such as license updates, extension installation) on already created BC containers when needed.

  1. Launch PowerShell or Windows Terminal (in PowerShell mode) as an administrator.
  2. Enter:
PowerShell
Install-PackageProvider -Name NuGet -force
Install-Module BcContainerHelper -force

If PowerShell blocks the installation of an external module, enter the following line and then retry the module installation from point 2:

PowerShell
Set-ExecutionPolicy Unrestricted -Scope LocalMachine

Step 3: Prepare the license file (optional)

If, as a consultant or developer, you have access to a Partner license for BC, you can install it immediately when installing BC on the container. First, prepare the license file:

  1. The license file must be generated for the same version of BC that you intend to run on the container.
  2. Place the license file in .flf format (for NAV and older BC versions) or in .bclicense format (for newer BC versions) in an easily accessible path, e.g.: C:\temp\my-partner-license.bclicense.

Step 4: Prepare the script that creates a BC container

This is definitely the longest step, but know that once the script is prepared, it can be used multiple times to create another BC containers, with all the changes to parameter values if needed (e.g., container name or BC version). It’s worth spending time on this and carefully choosing options to suit your needs. Below, I’ll try to describe everything so you can smoothly go through the whole process. Let’s get started:

  1. Launch PowerShell or Windows Terminal (in PowerShell mode) as an administrator.
  2. Launch the BC container creation wizard by entering the command:
PowerShell
New-BcContainerWizard
  1. On the Accept Eula screen, a description of the wizard will be displayed, which, based on your answers to the questions it asks, will generate a script to create a BC container that meets your needs. Below is a request to accept the license terms. Accept them: Y and press Enter.
Description of the wizard and request to accept the license terms
  1. On the Local Container or Azure VM screen, choose between creating a local container on the computer where you launched the wizard or creating a container on an Azure virtual machine (requires an Azure subscription). We choose the local container on Docker a, which is the default option – just press Enter.
  2. Choose the user authentication type for BC. I recommend Username/Password authentication, which is actually the NavUserPassword authentication method in BC. To set your own username and password for the administrator account (the first user with SUPER permissions), select option a and press Enter.
  3. Give your container a name. The container name should distinguish it from your other containers. Even if this is your first BC container, it’s worth giving it your own name. The name should be short and built using lowercase letters, numbers, and possibly a hyphen. Pressing Enter without entering a name will set the default name: bcserver.
Naming the created Business Central container
My own container naming scheme

I personally adopted a naming scheme based on the type of BC and its version.

For example, the container with BC on-premises version 2023 release wave 1 I would name with bcop22 (op as an abbreviation for On-Premises, while 22 for version number 2023 release wave 1 = v22). Then, container with BC online (sandbox) version 2023 release wave 2 I would name with bcol23 (ol as an abbreviation for OnLine). When I create a container with a preview version (so-called insider build), I use the abbreviation ib, e.g., bcib24. In particular cases, when I need a container for a specific purpose (not for general testing), I add a suffix after the hyphen, e.g., bcol23-blog for a container with the latest version (23) BC online, created for the purposes of today’s guide.

Use my naming scheme, develop your own, or live in chaos ;). After all, you are the captain of your container ship!

  1. On the Version screen, select the BC (or NAV) version you want to install on the container. You can choose from: the latest BC online (sandbox) version a, which is the default option – just press Enter, the latest BC on-premises version, preview versions (for the next major and next minor version), a specific build of BC online (sandbox) or BC on-premises, as well as specific versions down to the CU for: NAV 2018, NAV 2017, and NAV 2016.
Not all wizard options are described in this guide

For the purposes of the further part of the guide, I chose the default option, i.e., a container with the latest BC online (sandbox) version, which as of the publication date of this guide is 23.4. I think this will be the most common scenario for many of you – choosing the latest BC sanbox version for your containers.

Some screens and options in the wizard appear conditionally, depending on previously selected options. For example, if you select BC 14 or one of the NAV versions, you will see queries about installing a development environment for the C/AL language, etc., which I will not describe in the example of this guide. In the same time you will not see some screens that only apply to BC or only to new versions, etc.

  1. On the Country screen, select the localization version for the previously selected BC (or NAV) version.
The version of BC selected in the previous step is visible on the localization version selection screen
Range of available localization versions

It is also worth noting that the list of available localization versions includes not only countries covered by Microsoft’s localization but also those with a local language version, although the localization package itself is distributed by a local Partner. A global version W1 is also available.

  1. On the Test Toolkit screen, decide whether you want to install the Application Test Toolkit during container creation. It is needed for writing automated tests. If you do not intend to program on the created container, you can skip the toolkit installation d, which is the default option – just press Enter.

If you want to install the Application Test Toolkit later for your container, you can still do so using the command:

PowerShell
Import-TestToolkitToBCContainer -containerName <your-container-name>
Partner license required for the full toolkit

If you answered a to the above, meaning you want to install the full set of test tools, in one of the following steps it will be necessary to import the license file with the Partner license. Without this, the wizard cannot be completed and the container cannot be launched.

  1. If you answered a, b, or c to the above, the Performance Toolkit screen will appear where you can decide whether to install the Performance Toolkit (BCPT) extension for testing the performance of developed extensions.
  2. Choose Y on the Premium Plan screen if you want to set BC with the capabilities of a Premium license, or leave the default value N if you wish to keep BC with the capabilities of an Essential license. Of course, this can be changed later in BC on the Company Information page.
  3. On the Create Test Users screen, specify whether you want to create test users for different license levels: Essential, Premium, Team Member, External Accountant, Internal Administrator, Delegated Administrator.
  4. On the AL Base App Development screen, specify whether you intend develop custom code for the Base Application. It is also useful for debugging code and reviewing object code.
  5. If you answered Y to the above, the Export AL Base App screen will appear where you need to specify whether you want to export Base Application objects as a project for Visual Studio Code.
Partner license required for Base App export

If you answered Y to the above, meaning you want to export the project with Base Application objects, in one of the following steps it will be necessary to import the license file with the Partner license. Without this, the container cannot be launched.

  1. On the AL Language Extension screen, specify whether you want to use the version of the AL language extension for Visual Studio Code that matches the selected BC version – option N, default, or the latest available – option Y.
  2. On the License screen, you can (or must – see the above notes) provide a license file to be imported into the created container. Enter the full path to the license file that we prepared earlier (see step 3), e.g.: C:\temp\my-partner-license.bclicense and press Enter. If there is even one space in the path, enclose the entire path in double quotes, e.g.: "C:\My folder\License (BC23).bclicense".
Necessity (in my case) to provide the path to the license file due to previous choices
Cronus demo license

If the answers to the previous questions did not require you to provide a license file with the Partner license, pressing Enter without entering a file path will use the Cronus demo license.

  1. On the Database screen, in specific cases, you can indicate that you want to run BC on a copy of the SQL database you have (e.g., a copy of the customer’s production database that needs to be migrated or checked) or that you want to connect to an existing SQL database (e.g., on a SQL Server installed on the computer). Otherwise, use option a, the default, by pressing Enter, which will cause the container to be created with its own SQL database and this will be the Cronus demo database.
  2. In the case of choosing BC online (sandbox), the Multitenant screen will appear, where you decide whether the environment in the container should be multi-tenant or single-tenant. By default, BC online (sandbox) in the Docker container is installed as a multi-tenant environment and this should not cause any issues – press Enter.
  3. You can decide on the DNS configuration for the container if you have experienced problems with network name resolution during previous container installations. If not, press Enter.
  4. On the SSL screen, you can choose whether to secure network traffic for BC in the container or not. Containers in our scenario are usually used only from the computer on which they are created, never from outside, so theoretically SSL is not required. However, I recommend choosing option c to install a self-signed certificate, configure BC to handle HTTPS, and register the certificate on the computer. This will eliminate security warnings from web browsers, also some functionalities only work when SSL is enabled.
  5. On the Isolation screen, you can choose the isolation mode for the container. The topic is quite technical, but generally process isolation (option b) should be OK for most cases (when your Windows version corresponds to or is close to one of the operating system versions available in the images from the BC container repository hosted by Microsoft… – I said it’s a technical topic). Press Enter for the wizard to choose the most appropriate isolation method based on the comparison of operating system versions. However, if creating the container DOES NOT succeed with the process isolation mode, try again and set the isolation mode to Hyper-V isolation (option c).
  6. Set the RAM memory allocation limit on the Memory Limit screen. The system will dynamically allocate memory to the container in various ways depending on the chosen isolation mode (see the point above). However, if you do not want the container to use more memory in any situation, set the limit in gigabytes. Pressing Enter without entering a value will cause the container to run without a RAM limit in the case of process isolation mode or with 4 GB of RAM in the case of Hyper-V isolation mode.
  7. If you plan to create many similar containers, you can save the image in Docker under a friendly name, which will save some time on subsequent runs of the same script. Enter a name for the image if you want to save it. If you are not sure whether you will create many similar containers – do not save the image, press Enter without entering a name.
  8. Finally, you can save your generated script based on the answers in the form of a PowerShell script file. Enter a name for the file and press Enter. The file will be saved on your computer and opened in PowerShell ISE. If you press Enter without entering a name for the script, the wizard will ask if you want to run the script immediately without saving it. However, I recommend providing a name and saving it :)
Saving the PowerShell file with the generated script that creates a Business Central container
Saved and ready to run the generated script that creates a Business Central container

Step 5: Run the script and create a BC container

If in the previous step, in the last point, you did not enter a name for the script, you probably already ran it and the container is being created, you can skip to point 6 in this step. If, however, you saved it to a file, it was probably saved in your default Documents folder and is ready to run.

If after completing the previous step the PowerShell ISE application is still running with the generated script open, you can skip the first two points.

  1. Run PowerShell ISE as an administrator.
  2. Open the .ps1 file with the generated script that creates a BC container.
  3. Run the script by pressing F5 or the Run Script action from the toolbar.
  4. If on the Authentication screen of the wizard (see step 4, point 5) you chose option a to be able to set the username and password for the user yourself, a window will appear where you enter the Username and Password you want to set for the user in BC. Confirm the entered data with the OK button.
  5. The container creation process will begin. You can safely go make yourself a coffee ;)
Time to Launch

Creating the first container will take about 15 to 90 minutes (depending on Internet connection speed), while each another one will create much faster. For the subsequent containers, Docker will only need to download the missing elements, using the previously downloaded common elements (e.g., system components, SQL Server, IIS).

Creating another BC container in the same version as before, all artifact elements can be reused and nothing will need to be downloaded. Therefore, the creation time for subsequent BC containers can drop to as little as a few minutes.

  1. In the console panel of the PowerShell ISE application (the lower part of the application), you will be able to track the progress of the container creation process. Below, I describe roughly what is happening (for the curious – please expand the bar below).

  • The process starts with verifying if the script was run with administrator rights, if Hyper-V features are enabled, what the host operating system version is (on our computer), what the Docker version is,
  • Next, the existing container with the selected name will be removed (of course, only if it exists) along with any shortcuts to the container from the Desktop,

It’s worth to remember this! If you start creating a container with the name of an already existing container, the script will simply remove the existing container with the selected name and create a new one in its place without any additional dialog questions or confirmations.

  • The download of so-called artifacts containing references to images appropriate for the version of BC or NAV you selected will begin. You will see confirmation of the BC version for which the artifacts will be downloaded, where the downloaded files will be saved, and when they will be unpacked (7zip is used for that),
  • Then the download of all images required by the specified artifact will begin, containing libraries and binary files for Business Central itself, as well as all the components it needs (e.g., SQL Server, IIS, etc.),

The best part is that the images that were previously downloaded and are in use by other existing containers on your computer will not be downloaded again. Docker will share them, saving your disk resources!

  • The downloaded images will be checked for checksums, digitally signed, and used as the container image,
  • Then the container creation begins (the line with the entry Creating Container <your-container-name>), listing the main parameters for the container in terms of Business Central, such as the environment type (sandbox or on-premises), multi-tenancy, BC application version, and BC platform version, the isolation mode used, the license used, and others, then the container is created on Docker,
  • Installation of Business Central, SQL Server, IIS on the container takes place, copying the application server files, Web Client files, and some additional files for extensions, tests, etc. depending on the selected options,
  • CRONUS Demo Database is restored unless you chose otherwise,
  • Cronus license is imported,
  • The tenant is synchronized,
  • IP addresses and DNS names are handled, and an SSL certificate is generated and installed,
  • The web server (IIS) is configured,
  • Your Partner license is imported if you indicated one,
  • The sa user is configured for SQL Server,
  • A user in BC with SUPER permissions is created,
  • Premium capabilities are enabled for BC if you selected this,
  • A technical summary of the configured container with Business Central is displayed, including information about the container’s IP address accessible from the host, DNS address, Web Client address, links to download files (including the AL language extension for Visual Studio Code in the selected version), and information about the allocated and used RAM memory,
  • The line with the entry Ready for connections! signifies success and that you can now connect to your Business Central!

The script may not end yet, because depending on the container type, version, and options selected during the wizard, the script may still configure and/or install minor items:

  • The SSL certificate is registered in the computer’s certificate store if you chose so,
  • Shortcuts to the Desktop are created for: Web Client, BC admin console from the Command Prompt or PowerShell, and others depending on the selected options,
  • Custom Microsoft extensions and those that depended on the selected options are published, synchronized, and installed,
  • The project with Base Application is exported if you expressed this wish in the wizard,
  • The container may be restarted once again and…

  1. The Business Central container is created and ready to work! You can launch it from the shortcut to the Web Client created on the desktop or simply enter the Web Client address provided at the end of the script execution in the address bar of your favorite browser.

Web Client address (among others) visible at the end of the script execution (before publishing extensions)
Business Central login screen for NavUserPassword authentication
And here is our own containerized Business Central :)

Step 6: Install the extensions (optional)

On the BC container, you can install your own PTE and ISV extensions for which you have a runtime app (an application compiled into a .app package).

If you need to install, for example, Polish Localization or Localization for Poland, use your Partner access to IT.integro or Companial resources and download the runtime app corresponding to the BC version installed on the container. Similarly with other ISV extensions. PTE extensions can be published in the same way (using the compiled runtime app) or directly from Visual Studio Code.

  1. Place the .app packages of the extensions in versions corresponding to the Business Central version installed on the container in an easily accessible path, e.g.: C:\temp\extensions\<extension-name>.app.
  2. Run PowerShell or Windows Terminal (in PowerShell mode) as an administrator.
  3. Enter:
PowerShell
Publish-BcContainerApp -containerName <your-container-name> -appFile "C:\temp\extensions\<extension-name>.app" -skipVerification -sync -install
  1. The extension will be published, synchronized, and installed.
  2. Repeat point 3 for each extension you want to install.

That’s basically it. You’ve reached the finish line 🏁 good job! Whatever your goal in creating this BC environment is, it’s now ready, so… get to work! 💪 However, before you go testing or checking or programming on your new environment, check out some additional tips about your container:

Appendix 1: Reuse the script

When you need to create another Business Central container, you can of course go back to step 4 and go through the wizard again. Going through the wizard again will be much faster than the first time. But even quicker method, however, is to open the script you created the first time (in case you saved it) and change the appropriate parameters:

  1. In the line with the $containerName variable, change the name for the container.
  2. In the line with the $artifactUrl variable after the -type parameter, choose the container type: Sandbox for BC online version or OnPrem for BC on-premises version.
  3. After the -country parameter, you can change the localization version if you need a different one than before.
  4. After the -select parameter, you can choose from several values (in PowerShell ISE you can go through all available values by keep pressing the Tab ↹ key when the cursor is just behind the -select parameter and the space), so that the script selects the version from the latest release, next major, next minor, , etc.
  5. You can also replace the -select parameter with the -version parameter and then manually enter the version number of BC you want to install on the container. You can provide the version number with precision up to the major version, minor version, or even a specific build. If you provide the version with precision only up to the major version number, the script will select the latest released minor version (the newest in the given major version) and the latest build in that version. Numbers are separated by a period sign, e.g. -version 21 will install BC 21 in the latest minor version released for BC 21 and the latest build that has been released; -version 21.3 will install BC 21.3 with the latest build that has been released specifically for the 3rd minor version of BC 21; -version 21.3.51409.51727 will install exactly the build you indicate.
  6. In the line with the $licenseFile variable (if you have such in the script of course – it depends on whether you selected the appropriate license import option during script creation) adjust the path to the license file in the version you want to install on the container.
  7. Adjust the remaining values of variables and parameters of your script and run it!
Edited script for BC on-premises in minor release 21.10 in localization version W1
Monitor your computer’s resources

Despite all the advantages of containers and how they use computer resources, remember to monitor your computer’s resources used by containers on Docker (especially in terms of RAM and disk space usage).

Stop containers from the Docker Desktop application if you do not use them or use them rarely, and start them only when they are actually needed. This way, the main memory will not be reserved immediately when the computer starts.

Keep the number of containers at a reasonable level for yourself. Do you really still need those old environments from 2 years ago? Do they even still work? Do they have an active license? Maybe it’s worth removing them and freeing up some disk space…?

Appendix 2: Import a new license

If you imported a Partner license to the container, sooner or later you will need to update the license and import a new license file to replace the old one that has expired or is about to expire:

  1. Prepare the new license file as described in step 3.
  2. Run PowerShell or Windows Terminal (in PowerShell mode) as an administrator.
  3. Enter:
PowerShell
Import-BcContainerLicense -containerName <your-container-name> -licenseFile "C:\temp\my-partner-license.bclicense" -restart
  1. The license will be imported into the database on the indicated container, and the BC application server will automatically restart due to the -restart parameter, so that the new license takes effect immediately.

Have fun! 😎

Tags:
3LikesShare Post
Hide comments

1 Comment

  • Brigida
    Posted Monday, 27 October 2025 at 14:37

    Keep this gong please, great job!

    0Likes Reply

Leave a comment

You may also like

Tuesday, 28 January 2025
Microsoft is sweeping away CDX environments and reducing limits for Partners
Tuesday, 6 February 2024
How to create a demonstration environment on CDX

Featured blog posts

Versions & Releases
What’s new and planned for Dynamics 365 Business Central 26 (2025 release wave 1)
Sales
Sales Order Agent will receive and process all your orders in BC
Onboarding & Help
What to use the Page Scripting Tool for

Marcin Karpacz © 2026. All Rights Reserved.

Sign Up to Our Newsletter

Be the first to know the latest updates