{"title":"Running a container-based development environment","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-running-container-development/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-running-container-development, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-running-container-development","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Overview of how to run a container-based development.","date":"2023-10-04","meta":{"topic":"how-to"},"outline":[{"level":1,"title":"Running a container-based development environment","slug":"running-a-container-based-development-environment","at":0,"chars":7431},{"level":2,"title":"Install and configure Docker","slug":"install-and-configure-docker","at":173,"chars":1104},{"level":2,"title":"Set up Business Central using the BCContainerHelper PowerShell module","slug":"set-up-business-central-using-the-bccontainerhelper-powershell-module","at":1277,"chars":1073},{"level":2,"title":"Quick start: Create new container","slug":"quick-start-create-new-container","at":2350,"chars":3050},{"level":3,"title":"Issues setting up Business Central containers?","slug":"issues-setting-up-business-central-containers","at":3717,"chars":1408},{"level":3,"title":"Engage with us on GitHub - BcContainerHelper","slug":"engage-with-us-on-github---bccontainerhelper","at":5125,"chars":275},{"level":2,"title":"After setup","slug":"after-setup","at":5400,"chars":1198},{"level":2,"title":"Common usage scenarios","slug":"common-usage-scenarios","at":6598,"chars":650},{"level":3,"title":"Installing an app","slug":"installing-an-app","at":6769,"chars":479},{"level":2,"title":"Related information","slug":"related-information","at":7248,"chars":183}],"text":"# Running a container-based development environment\nDynamics 365 Business Central is available as artifacts for running on Docker on a Windows system with Docker installed.\n## Install and configure Docker\nInstall Docker and configure it for Windows Containers.\n1. Choose the version of Docker that's appropriate for the host operating system.\n  For Windows Desktop, use Docker Desktop<https://docs.docker.com/desktop/install/windows-install/> - (option to qualify for free SKU - license might be required).\n  For Windows Server, use Mirantis Container Runtime<https://docs.mirantis.com/mcr/23.0/overview.html> - (option to qualify for free SKU - license might be required).\n  An alternative is to use Docker Engine, which is open source and community-driven.\n2. For Windows Desktop, switch Docker to use Windows containers. By default Docker uses Linux containers.\n To switch to Windows containers, in the Taskbar, right-click the Docker icon, and then select Switch to Windows Containers. See https://docs.docker.com/docker-for-windows/#switch-between-windows-and-linux-containers.\n> NOTE\n> You can run Business Central on Docker using Docker commands, or you can use the BCContainerHelper PowerShell module. The BCContainerHelper module removes complexity of running Docker.\n## Set up Business Central using the BCContainerHelper PowerShell module\nTo support the use of containers, optional PowerShell scripts are available, which support setup of development environments. Use the BCContainerHelper to work with containers. On a device running a supported Windows version:\n1. Start PowerShell as an administrator.\n> IMPORTANT\n> For 2026 release wave 1 (version 28.0) containers, use Windows PowerShell 5.1 if you expect to run management functions such as `Restart-BcContainer`, `Get-BcContainerAppInfo`, and `Publish-BcContainerApp`. These functions rely on Business Central admin modules. PowerShell 7 has a known issue that causes the loading Business Central admins modules to fail, resulting in module import errors. See ../upgrade/known-issues.\n1. Run the following command to install the BCContainerHelper module.\n ```powershell\n install-module BCContainerHelper -force\n ```\n1. To get a list of functions that are available in the BCContainerHelper module, run the following command:\n ```powershell\n Write-BCContainerHelperWelcomeText\n ```\n## Quick start: Create new container\nTo get started quickly with a sandbox container on the latest Business Central version, run the following command from the BCContainerHelper module:\n```powershell\n$artifactUrl = Get-BcArtifactUrl -type sandbox -country us -select Latest\nNew-BCContainer -accept_eula -containerName mysandbox -artifactUrl $artifactUrl\n```\n> NOTE\n> If you want to try out the Insider builds of Business Central, you can access these builds by specifying NextMajor or NextMinor to the select parameter on `Get-BcArtifactUrl`. You also need to add `-accept_insiderEula` to both Get-BcArtifactUrl and New-BCContainer in order to get Insider builds.\nThe BCContainerHelper creates a folder on the C:\\ drive called bcartifacts.cache for caching artifacts. It also creates a folder under C:\\ProgramData called BCContainerHelper and places all working files underneath that folder. The C:\\ProgramData\\BCContainerHelper folder is shared to the container for transfer of files etc. If you don't specify a username and a password, it asks for your password and uses the current Windows username. If you specify your windows password, the container setup uses Windows Authentication integrated with the host. The BCContainerHelper also creates shortcuts on the desktop for the Business Central web client, a container prompt, and a container PowerShell prompt.\n### Issues setting up Business Central containers?\nIf you encounter issues setting up Business Central containers, there are a few things you can try before creating an issue on GitHub.\n1. Make sure you're running the latest version of Docker<https://www.docker.com/products/docker-desktop/> and the latest version of the BcContainerHelper module<https://www.powershellgallery.com/packages/BcContainerHelper>.\n2. If the container fails during creation:\n  Check that you have enough memory (Business Central containers use at least 6 GB) and enough disk space (artifacts and container images uses ~15 GB)\n  You can try to add `-isolation hyperv` to your `New-BcContainer` command to see whether Hyper-V isolation solves the problem.\n3. If the container is created, but you can't navigate to the container in a browser?\n  You can try to include the `-updateHosts` parameter on your `New-BcContainer` command. This parameter adds an entry in your hosts file for the container.\n  You can try to use Username/Password authentication instead of Windows authentication adding `-auth UserPassword -credential (Get-Credential)` to your `New-BcContainer` command.\n4. Try the most basic New-BcContainer command with the suggested arguments from this article to check whether the problem stems from advanced usage.\n5. Remember to include the full output of your New-BcContainer command when creating an issue on GitHub.\n### Engage with us on GitHub - BcContainerHelper\nUse this repo to collaborate around the source code and the scripts of BcContainerHelper PowerShell module for Business Central: https://github.com/Microsoft/NavContainerHelper<https://github.com/Microsoft/NavContainerHelper>\n## After setup\nAfter starting the Docker container, you see log entries similar to the following example:\n```\nInitializing...\nStarting Container\nHostname is b8c6941bb168\n...\nContainer IP Address: 192.168.57.195\nContainer Hostname  : mysandbox\nContainer Dns Name  : mysandbox\nWeb Client          : http://mysandbox/BC/?tenant=default\nDev. Server         : http://mysandbox\nDev. ServerInstance : BC\nDev. Server Tenant  : default\nSetting mysandbox-default to 127.0.0.1 in container hosts file\n\nFiles:\nhttp://mysandbox:8080/ALLanguage.vsix\n\nInitialization took 66 seconds\nReady for connections!\n```\nAt this point, you can open your browser and type in the web client URL from the log. You're prompted to sign in with the Admin Username/Password that is shown.\n> NOTE\n> The container image uses a so called self-signed certificate for HTTPS communication. As a result, your browser might warn you that the page you're requesting is unsafe. In those specific circumstances, and only for test and development environments, it's safe to ignore this warning. If you want to resolve this warning, you can install the certificate on your PC. For more information, see the link under Files in the log entries.\n## Common usage scenarios\nThe BCContainerHelper PowerShell module supports many scenarios that you might need as a developer. In this section, we highlight a few of them.\n### Installing an app\nUploading per-tenant extensions isn't supported in on-premises environments. If you want to install an app/extension using an .app file, then you can use the _Publish-BcContainerApp_ commandlet.\nUse this example to get started:\n```powershell\nPublish-BcContainerApp -appFile <full path to file> -tenant <tenant name> -install -containerName <container name>\n```\nUse `help Publish-BcContainerApp -detailed` to get a full list of parameters and functionality.\n## Related information\nGet Started with AL<devenv-get-started>\ndevenv-keyboard-shortcuts\nAL Development Environment<devenv-reference-overview>\nFAQ for Developing in AL<devenv-dev-faq>"}