Introduction
Nowadays, with the widespread adoption of microservices across major companies, using Windows Server to host SQL Server remains the gold standard. However, there are still certain scenarios—or even specific environments—where deploying SQL Server in containerized setups using the Docker engine becomes necessary. In this article, I will offer practical tips based on my hands-on experience, focusing on several often-overlooked aspects of enterprise-level deployment. This article assumes basic familiarity with both Docker and SQL Server.
Prerequisites
For the Docker environment, set up a Linux OS (mini install or server install) with docker installed, in this case I will show you in a Ubuntu 24.04.1 LTS with docker 28.2.2 installed, in case reader don't any experience of install docker on Ubuntu, I prefer to suggest you to using the following script:
apt install -y apt-transport-https ca-certificates curl software-properties-common curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o docker.gpg gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg docker.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null apt update apt install -y docker-ce docker-ce-cli containerd.io systemctl restart docker systemctl enable docker systemctl status docker
The hardware requirements are at least 2GB RAM and 2GB disk space, add more CPU cores, RAM size and disk space as needed.
Advice 1: The Mostly ignored parameter for running a docker container
As mentioned in Microsoft articles, using the following commands to run a docker container to host the SQL Server instance.
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<password>" -p 1433:1433 --name sql1 --hostname sql1 -d mcr.microsoft.com/mssql/server:2025-latest
However, the mostly ignored parameter is "--restart=unless-stopped". Without this parameter, the container will not start automatically from docker host server reboot.
Imagine how to set up a Docker server such that, after a restart due to a failure, the Docker service can automatically start up again. However, the container does not automatically start up, meaning it cannot recover automatically from the failure. This would be a very bad situation, just like if the SQL Server service is not set to start automatically. An exception to this parameter is when the container is manually shut down by an administrator, in which case it will not automatically start up again, so we should run the command like the following:
docker run --restart=unless-stopped -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=123123Ppl@' -p 1433:1433 -d mcr.microsoft.com/mssql/server:2022-latest
Advice 2: Correct permission for mapping folders to docker container
Another important thing also we must set up the folder mapping or docker volume for persistent SQL Server data and configuration storage, there are two ways to achieve the goal:
The first is to use the docker volume with the following commands refer to Microsoft articles:
docker run -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<password>' -p 1433:1433 -v sqlvolume:/var/opt/mssql -d mcr.microsoft.com/mssql/server:2022-latest
The second is to use mapping folder to docker container refer to Microsoft articles:
docker run -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<password>' \ -p 1433:1433 \ -v <host directory>/data:/var/opt/mssql/data \ -v <host directory>/log:/var/opt/mssql/log \ -v <host directory>/secrets:/var/opt/mssql/secrets \ -d mcr.microsoft.com/mssql/server:2022-latest
As I researched some articles about the second solution, I found most articles missing how to setting least privilege for the folders, which need to be mapped to the container,
In this case I created three folders mapped to docker container with following commands:
mkdir /mssql mkdir /mssql/data /mssql/log /mssql/secrets
If the the folders on docker host server without enough permission for the user "mssql" in container to access, will get the error like this:
Editor: IS someone supposed to run this inside the container? Each time a container is created? How do they do this?
However, excessive permission settings may result in unrelated accounts in Linux accessing and modifying files related to SQL Server, so please use the following commands to set the permission:
chown -R 10001:0 /mssql/data /mssql/log /mssql/secrets chmod -R 700 /mssql/data /mssql/log /mssql/secrets
The "10001" is uid of mssql user in the container which will also mapped to the docker host server.
Editor: The sentence below isn't a sentence and doesn't make sense. This isn't clear what a user needs to do.
From the following Dockerfile mentioned the uid of mssql:
Then run the following commands to start a container on docker host server:
docker run --restart=unless-stopped -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=SAPassword' -p 1433:1433 -v /mssql/data:/var/opt/mssql/data -v /mssql/log:/var/opt/mssql/log -v /mssql/secrets:/var/opt/mssql/secrets -d mcr.microsoft.com/mssql/server:2022-latest
Advice 3: Docker hosted SQL Server post installation check
We must check the SQL Server installation if succeeded. Please note even if the docker container is running, this doesn't mean the SQL server was set up without any issue. Please check the container logs to see the installation progress. Use the command to check the SQL Server installation progress:
docker logs -f 'container name'
Once we get the following output, that means installation succeeded:
Check the files under the following folders (the folders on the docker host mapped to container): /mssql/log, /mssql/data and /mssql/secrets.
If you can see the following outputs that means installation succeeded. Please use the 'ls -l' or 'll' to list files under the folders:
Under the folder /mssql/data:
Under the folder /mssql/log
Under the folder /mssql/secrets
Test the SQL Server connection in the container and run SQL query like the following. Enter the docker container with this command:
docker exec -it -u root 26a7ebc7f712 /bin/bash
Then use sqlcmd to connect to SQL server and run a SQL query. If you got this info, that means installation succeeded:
Please add the parameter "-C " in the above commands:
/opt/mssql-tools18/bin/sqlcmd -S localhost -U SA -P 'SAPassword' -C -Q "SELECT @@VERSION"
If you run the commands without "-C" for example:
/opt/mssql-tools18/bin/sqlcmd -S localhost -U SA -P 'SAPassword'
You will get this error since the SQL Server use self-signed certificate:
Last but not least, use the following commands to check the CPU usage, memory usage of the docker container with the following commands:
docker stats
The output is:
Advice 4. Remember to enable SQL Server agent
As SQL Server agent is quite important for running jobs, but it will not be enabled as default. The first time you use SSMS to connect your SQL server after all SQL Server set up done you will find the SQL Server agent is in disable status:
Then enter the container in docker to enable SQL Server agent:
Remember it is impossible to run 'systemctl restart mssql-server.service' in the container inside, so just restart the target container like the following:
Once the container is running again, then connect to SQL Server instance by SSMS again, as we can see the SQL Server agent already been enabled:
Other Advice
- Please change the container exposed port for SQL Server, for example using '-p 14133:1433' to replace '-p 1433:1433'.
- If we use multiple containers to host SQL Server instances on one docker host, it is essential to set limit for CPU cores and memory for each container
Summary
In this article I shared some useful advices about how to use the docker to host SQL Server in production environment. Especially, it helps SQL Server DBA who are using it for the first time avoid some of the most common issues. These issues, which are easily overlooked, are not explicitly mentioned in Microsoft's official technical documentation, but they conform to best practices and are essential. The best practices covered in this article are relatively limited, I also welcome suggestions and corrections from readers.
References
Run SQL Server Linux container images with Docker: https://learn.microsoft.com/en-us/sql/linux/quickstart-install-connect-docker?view=sql-server-ver17&tabs=cli&pivots=cs1-bash
Configure and customize SQL Server Linux containers: https://learn.microsoft.com/en-us/sql/linux/sql-server-linux-docker-container-configure?view=sql-server-ver17&pivots=cs1-bash#persist
Restore a SQL Server database in a Linux container: https://learn.microsoft.com/en-us/sql/linux/tutorial-restore-backup-in-sql-server-container?view=sql-server-ver17&tabs=cli
Troubleshoot SQL Server Docker containers: https://learn.microsoft.com/en-us/sql/linux/sql-server-linux-docker-container-troubleshooting?view=sql-server-ver17&pivots=cs1-bash