> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/server/knowledge-base/how-to-articles/devolutions-server-docker-deployment.md).

# Deploy Devolutions Server with Docker

This article shows how to deploy Devolutions Server using Docker.

{% hint style="info" %}
For the sake of simplicity, Devolutions Server's Docker image version is written `20XX.X` in the code blocks of this article. Change this variable to the version you wish to use.
{% endhint %}

### Prerequisites

* Docker version `20.10.X` or later. On macOS ARM64, use `--platform linux/amd64` during the initialization phase due to assembly compatibility. The runtime mode runs natively on ARM64.
* An SQL Server instance properly [set up for Devolutions Server](https://docs.devolutions.net/server/getting-started/installation/database-setup/).
* The minimum [system requirements](https://docs.devolutions.net/server/overview/system-requirements/) to run Devolutions Server.

{% tabs %}
{% tab title="Windows" %}

### Devolutions Server first time setup

1. Create a dedicated login and database using an admin account (for example, `sa` or an Azure SQL admin). Grant [least-privilege access](https://docs.devolutions.net/server/kb/knowledge-base/pre-deployment-account-survey/#windows-sql-accounts) to Devolutions Server.
2. Pull the latest [Devolutions Server Docker image](https://hub.docker.com/r/devolutions/devolutions-server):

   ```powershell
   docker pull devolutions/devolutions-server:release-20XX.X
   ```
3. Run Devolutions Server in initialization mode to create the database schema and its first administrator, generate encryption keys, and configure HTTPS with a self-signed certificate. Save `App_Data` so the encryption configuration is retrievable for the next step.

```powershell
docker volume create dvls-init-data

docker run --rm `
  -e DATABASE_HOST=your-sql-server.database.windows.net `
  -e DATABASE_NAME=dvls `
  -e DATABASE_USERNAME=dvls_user `
  -e DATABASE_PASSWORD='YourSecurePassword!' `
  -e HOSTNAME=localhost `
  -e WEB_SCHEME=https `
  -e PORT=5000 `
  -e DVLS_INIT=true `
  -v dvls-init-data:/opt/devolutions/dvls/App_Data `
  -p 5000:5000 `
  devolutions/devolutions-server:release-20XX.X
```

4. Extract `encryption.config` from the initialization volume:

   ```powershell
   docker run --rm `
     -v dvls-init-data:/data `
     alpine `
     cat /data/encryption.config
   ```
5. Convert the extracted file to base64 and store it securely as it will be needed for every runtime start:

   ```powershell
   docker run --rm `
     -v dvls-init-data:/data `
     alpine `
     cat /data/encryption.config > $env:TEMP\encryption.config

   $content = Get-Content -Path "$env:TEMP\encryption.config" -Raw
   $bytes = [System.Text.Encoding]::UTF8.GetBytes($content)
   $base64 = [System.Convert]::ToBase64String($bytes)
   $base64 | Out-File -FilePath "$env:TEMP\encryption.config.b64" -NoNewline -Encoding ASCII
   ```
6. Start Devolutions Server using the base64 encryption configuration. Once this is done, use the `docker ps` and `docker logs dvls-server` commands to make sure everything is in working order.

   ```powershell
   $encryptionConfig = Get-Content "$env:TEMP\encryption.config.b64" -Raw

   docker run -d --name dvls-server `
     -e DATABASE_HOST=your-sql-server.database.windows.net `
     -e DATABASE_NAME=dvls `
     -e DATABASE_USERNAME=dvls_user `
     -e DATABASE_PASSWORD='YourSecurePassword!' `
     -e HOSTNAME=localhost `
     -e WEB_SCHEME=https `
     -e PORT=5000 `
     -e DVLS_ENCRYPTION_CONFIG_B64="$encryptionConfig" `
     -p 5000:5000 `
     devolutions/devolutions-server:release-20XX.X
   ```
7. Access the web interface by opening `https://localhost:5000` in your browser. Go past the self-signed certificate security warning by clicking ***Advanced*** – ***Proceed***. You can mount a custom TSL certificate later.
8. Log in by using `dvls-admin` for both the username and password.

{% hint style="danger" %}
Immediately after login, change the default password by heading to ***Administration*** – ***Users***, clicking on the vertical ellipsis button of the `dvls-admin` user, and selecting ***Change password***.
{% endhint %}

9. Make sure that Devolutions Server is running with `DVLS_ENCRYPTION_CONFIG_B64`, its web interface is accessible, and `encryption.config.b64` is saved in a secure location (it is needed for every restart and redeployment). Once this is done, the temporary initialization volume can be safely removed:

   ```powershell
   docker volume rm dvls-init-data
   ```

### Operating modes

DVLS Docker container operates in three distinct modes:

| Mode                      | Environment Variable    | Purpose          | Behavior                                                     |
| ------------------------- | ----------------------- | ---------------- | ------------------------------------------------------------ |
| **Runtime** **(default)** | No special variables    | Normal operation | Starts web server and keeps running.                         |
| **Initialization**        | `DVLS_INIT=true`        | First-time setup | Creates database schema, administrator user, then exits.     |
| **Update**                | `DVLS_UPDATE_MODE=true` | Database upgrade | Backs up configuration files, migrates database, then exits. |

{% hint style="info" %}
**Initialization** and **Update** modes are mutually exclusive.
{% endhint %}

### Custom port

Change the port Devolutions Server listens on by setting the `PORT` environment variable, e.g., with the `8080` port as in the example below:

```powershell
docker run -d --name dvls-server `
  -e DATABASE_HOST=your-sql-server.database.windows.net `
  -e DATABASE_NAME=dvls `
  -e DATABASE_USERNAME=dvls_user `
  -e DATABASE_PASSWORD='YourSecurePassword!' `
  -e HOSTNAME=localhost `
  -e WEB_SCHEME=https `
  -e PORT=8080 `
  -p 8080:8080 `
  devolutions/devolutions-server:release-20XX.X
```

### Mount a custom TSL certificate

Mount your own certificate files instead of using the auto-generated self-signed certificate:

```powershell
mkdir -p /host/path/certs
cp /path/to/server.pem /host/path/certs/
cp /path/to/server.key /host/path/certs/

docker run -d --name dvls-server `
  -e DATABASE_HOST=your-sql-server.database.windows.net \
  -e DATABASE_NAME=dvls `
  -e DATABASE_USERNAME=dvls_user `
  -e DATABASE_PASSWORD='YourSecurePassword!' `
  -e HOSTNAME=devolutions-server.company.com `
  -e WEB_SCHEME=https `
  -e PORT=5000 `
  -e TLS_CERTIFICATE_FILE=/opt/devolutions/dvls/certs/server.pem `
  -e TLS_PRIVATE_KEY_FILE=/opt/devolutions/dvls/certs/server.key `
  -p 5000:5000 `
  -v /host/path/certs:/opt/devolutions/dvls/certs:ro `
  devolutions/devolutions-server:release-20XX.X
```

### Container management

| Commands                   | Functions             |
| -------------------------- | --------------------- |
| `docker start dvls-server` | Starts the container. |
| `docker stop dvls-server`  | Stops the container.  |
| `docker rm dvls-server`    | Remove the container. |

{% hint style="info" %}
Removing the container is safe as long as you have the `encryption.config.b64` file, access to your SQL Server database, and your environment variables documented.
{% endhint %}
{% endtab %}

{% tab title="macOS" %}

### Devolutions Server first time setup

1. Create a dedicated login and database using an admin account (for example, `sa` or an Azure SQL admin). Grant [least-privilege access](https://docs.devolutions.net/server/kb/knowledge-base/pre-deployment-account-survey/#windows-sql-accounts) to Devolutions Server.
2. Pull the latest [Devolutions Server Docker image](https://hub.docker.com/r/devolutions/devolutions-server):

   ```bash
   docker pull devolutions/devolutions-server:release-20XX.X
   ```
3. Run Devolutions Server in initialization mode to create the database schema and its first administrator, generate encryption keys, and configure HTTPS with a self-signed certificate. Save `App_Data` so the encryption configuration is retrievable for the next step.

On macOS, this is where to add `--platform linux/amd64`.

```bash
docker volume create dvls-init-data

docker run --rm \
  -e DATABASE_HOST=your-sql-server.database.windows.net \
  -e DATABASE_NAME=dvls \
  -e DATABASE_USERNAME=dvls_user \
  -e DATABASE_PASSWORD='YourSecurePassword!' \
  -e HOSTNAME=localhost \
  -e WEB_SCHEME=https \
  -e PORT=5000 \
  -e DVLS_INIT=true \
  -v dvls-init-data:/opt/devolutions/dvls/App_Data \
  -p 5000:5000 \
  devolutions/devolutions-server:release-20XX.X
```

4. Extract `encryption.config` from the initialization volume:

   ```bash
   docker run --rm \
     -v dvls-init-data:/data \
     alpine \
     cat /data/encryption.config
   ```
5. Convert the extracted file to base64 and store it securely as it will be needed for every runtime start:

   ```bash
   docker run --rm \
     -v dvls-init-data:/data \
     alpine \
     cat /data/encryption.config > /tmp/encryption.config

   base64 -i /tmp/encryption.config -o /tmp/encryption.config.b64
   ```
6. Start Devolutions Server using the base64 encryption configuration. Once this is done, use the `docker ps` and `docker logs dvls-server` commands to make sure everything is in working order:

   ```bash
   docker run -d --name dvls-server \
     -e DATABASE_HOST=your-sql-server.database.windows.net \
     -e DATABASE_NAME=dvls \
     -e DATABASE_USERNAME=dvls_user \
     -e DATABASE_PASSWORD='YourSecurePassword!' \
     -e HOSTNAME=localhost \
     -e WEB_SCHEME=https \
     -e PORT=5000 \
     -e DVLS_ENCRYPTION_CONFIG_B64="$(cat /tmp/encryption.config.b64)" \
     -p 5000:5000 \
     devolutions/devolutions-server:release-20XX.X
   ```
7. Access the web interface by opening `https://localhost:5000` in your browser. Go past the self-signed certificate security warning by clicking ***Advanced*** – ***Proceed***. You can mount a custom TSL certificate later.
8. Log in by using `dvls-admin` for both the username and password.

{% hint style="danger" %}
Immediately after login, change the default password by heading to ***Administration*** – ***Users***, clicking on the vertical ellipsis button of the `dvls-admin` user, and selecting ***Change password***.
{% endhint %}

9. Make sure that Devolutions Server is running with `DVLS_ENCRYPTION_CONFIG_B64`, its web interface is accessible, and `encryption.config.b64` is saved in a secure location (it is needed for every restart and redeployment). Once this is done, the temporary initialization volume can be safely removed:

   ```bash
   docker volume rm dvls-init-data
   ```

### Operating modes

DVLS Docker container operates in three distinct modes:

| Mode                      | Environment Variable    | Purpose          | Behavior                                                     |
| ------------------------- | ----------------------- | ---------------- | ------------------------------------------------------------ |
| **Runtime** **(default)** | No special variables    | Normal operation | Starts web server and keeps running.                         |
| **Initialization**        | `DVLS_INIT=true`        | First-time setup | Creates database schema, administrator user, then exits.     |
| **Update**                | `DVLS_UPDATE_MODE=true` | Database upgrade | Backs up configuration files, migrates database, then exits. |

{% hint style="info" %}
**Initialization** and **Update** modes are mutually exclusive.
{% endhint %}

### Custom port

Change the port Devolutions Server listens on by setting the `PORT` environment variable, e.g., with the `8080` port as in the example below:

```bash
docker run -d --name dvls-server \
  -e DATABASE_HOST=your-sql-server.database.windows.net \
  -e DATABASE_NAME=dvls \
  -e DATABASE_USERNAME=dvls_user \
  -e DATABASE_PASSWORD='YourSecurePassword!' \
  -e HOSTNAME=localhost \
  -e WEB_SCHEME=https \
  -e PORT=8080 \
  -p 8080:8080 \
  devolutions/devolutions-server:release-20XX.X
```

### Mount a custom TSL certificate

Mount your own certificate files instead of using the auto-generated self-signed certificate:

```bash
mkdir -p /host/path/certs
cp /path/to/server.pem /host/path/certs/
cp /path/to/server.key /host/path/certs/

docker run -d --name dvls-server \
  -e DATABASE_HOST=your-sql-server.database.windows.net \
  -e DATABASE_NAME=dvls \
  -e DATABASE_USERNAME=dvls_user \
  -e DATABASE_PASSWORD='YourSecurePassword!' \
  -e HOSTNAME=devolutions-server.company.com \
  -e WEB_SCHEME=https \
  -e PORT=5000 \
  -e TLS_CERTIFICATE_FILE=/opt/devolutions/dvls/certs/server.pem \
  -e TLS_PRIVATE_KEY_FILE=/opt/devolutions/dvls/certs/server.key \
  -p 5000:5000 \
  -v /host/path/certs:/opt/devolutions/dvls/certs:ro \
  devolutions/devolutions-server:release-20XX.X
```

### Container management

| Commands                   | Functions             |
| -------------------------- | --------------------- |
| `docker start dvls-server` | Starts the container. |
| `docker stop dvls-server`  | Stops the container.  |
| `docker rm dvls-server`    | Remove the container. |

{% hint style="info" %}
Removing the container is safe as long as you have the `encryption.config.b64` file, access to your SQL Server database, and your environment variables documented.
{% endhint %}
{% endtab %}

{% tab title="Linux" %}

### Devolutions Server first time setup

1. Create a dedicated login and database using an admin account (for example, `sa` or an Azure SQL admin). Grant [least-privilege access](https://docs.devolutions.net/server/kb/knowledge-base/pre-deployment-account-survey/#windows-sql-accounts) to Devolutions Server.
2. Pull the latest [Devolutions Server Docker image](https://hub.docker.com/r/devolutions/devolutions-server):

   ```bash
   docker pull devolutions/devolutions-server:release-20XX.X
   ```
3. Run Devolutions Server in initialization mode to create the database schema and its first administrator, generate encryption keys, and configure HTTPS with a self-signed certificate. Save `App_Data` so the encryption configuration is retrievable for the next step.

```bash
docker volume create dvls-init-data

docker run --rm \
  -e DATABASE_HOST=your-sql-server.database.windows.net \
  -e DATABASE_NAME=dvls \
  -e DATABASE_USERNAME=dvls_user \
  -e DATABASE_PASSWORD='YourSecurePassword!' \
  -e HOSTNAME=localhost \
  -e WEB_SCHEME=https \
  -e PORT=5000 \
  -e DVLS_INIT=true \
  -v dvls-init-data:/opt/devolutions/dvls/App_Data \
  -p 5000:5000 \
  devolutions/devolutions-server:release-20XX.X
```

4. Extract `encryption.config` from the initialization volume:

   ```bash
   docker run --rm \
     -v dvls-init-data:/data \
     alpine \
     cat /data/encryption.config
   ```
5. Convert the extracted file to base64 and store it securely as it will be needed for every runtime start:

   ```bash
   docker run --rm \
     -v dvls-init-data:/data \
     alpine \
     cat /data/encryption.config > /tmp/encryption.config

   base64 -w 0 /tmp/encryption.config > /tmp/encryption.config.b64
   ```
6. Start Devolutions Server using the base64 encryption configuration. Once this is done, use the `docker ps` and `docker logs dvls-server` commands to make sure everything is in working order:

   ```bash
   docker run -d --name dvls-server \
     -e DATABASE_HOST=your-sql-server.database.windows.net \
     -e DATABASE_NAME=dvls \
     -e DATABASE_USERNAME=dvls_user \
     -e DATABASE_PASSWORD='YourSecurePassword!' \
     -e HOSTNAME=localhost \
     -e WEB_SCHEME=https \
     -e PORT=5000 \
     -e DVLS_ENCRYPTION_CONFIG_B64="$(cat /tmp/encryption.config.b64)" \
     -p 5000:5000 \
     devolutions/devolutions-server:release-20XX.X
   ```
7. Access the web interface by opening `https://localhost:5000` in your browser. Go past the self-signed certificate security warning by clicking ***Advanced*** – ***Proceed***. You can mount a custom TSL certificate later.
8. Log in by using `dvls-admin` for both the username and password.

{% hint style="danger" %}
Immediately after login, change the default password by heading to ***Administration*** – ***Users***, clicking on the vertical ellipsis button of the `dvls-admin` user, and selecting ***Change password***.
{% endhint %}

9. Make sure that Devolutions Server is running with `DVLS_ENCRYPTION_CONFIG_B64`, its web interface is accessible, and `encryption.config.b64` is saved in a secure location (it is needed for every restart and redeployment). Once this is done, the temporary initialization volume can be safely removed:

   ```bash
   docker volume rm dvls-init-data
   ```

### Operating modes

DVLS Docker container operates in three distinct modes:

| Mode                      | Environment Variable    | Purpose          | Behavior                                                     |
| ------------------------- | ----------------------- | ---------------- | ------------------------------------------------------------ |
| **Runtime** **(default)** | No special variables    | Normal operation | Starts web server and keeps running.                         |
| **Initialization**        | `DVLS_INIT=true`        | First-time setup | Creates database schema, administrator user, then exits.     |
| **Update**                | `DVLS_UPDATE_MODE=true` | Database upgrade | Backs up configuration files, migrates database, then exits. |

{% hint style="info" %}
**Initialization** and **Update** modes are mutually exclusive.
{% endhint %}

### Custom port

Change the port Devolutions Server listens on by setting the `PORT` environment variable, e.g., with the `8080` port as in the example below:

```bash
docker run -d --name dvls-server \
  -e DATABASE_HOST=your-sql-server.database.windows.net \
  -e DATABASE_NAME=dvls \
  -e DATABASE_USERNAME=dvls_user \
  -e DATABASE_PASSWORD='YourSecurePassword!' \
  -e HOSTNAME=localhost \
  -e WEB_SCHEME=https \
  -e PORT=8080 \
  -p 8080:8080 \
  devolutions/devolutions-server:release-20XX.X
```

### Mount a custom TSL certificate

Mount your own certificate files instead of using the auto-generated self-signed certificate:

```bash
mkdir -p /host/path/certs
cp /path/to/server.pem /host/path/certs/
cp /path/to/server.key /host/path/certs/

docker run -d --name dvls-server \
  -e DATABASE_HOST=your-sql-server.database.windows.net \
  -e DATABASE_NAME=dvls \
  -e DATABASE_USERNAME=dvls_user \
  -e DATABASE_PASSWORD='YourSecurePassword!' \
  -e HOSTNAME=devolutions-server.company.com \
  -e WEB_SCHEME=https \
  -e PORT=5000 \
  -e TLS_CERTIFICATE_FILE=/opt/devolutions/dvls/certs/server.pem \
  -e TLS_PRIVATE_KEY_FILE=/opt/devolutions/dvls/certs/server.key \
  -p 5000:5000 \
  -v /host/path/certs:/opt/devolutions/dvls/certs:ro \
  devolutions/devolutions-server:release-20XX.X
```

### Container management

| Commands                   | Functions             |
| -------------------------- | --------------------- |
| `docker start dvls-server` | Starts the container. |
| `docker stop dvls-server`  | Stops the container.  |
| `docker rm dvls-server`    | Remove the container. |

{% hint style="info" %}
Removing the container is safe as long as you have the `encryption.config.b64` file, access to your SQL Server database, and your environment variables documented.
{% endhint %}
{% endtab %}
{% endtabs %}

#### See also

* [Security checklist](https://docs.devolutions.net/server/getting-started/security-checklist/)
* [Devolutions Server deployment to Azure App Service using a container](https://docs.devolutions.net/server/kb/how-to-articles/devolutions-server-docker-deployment/azure-app-service-deployment/)
* [Advanced Docker configuration for Devolutions Server](https://docs.devolutions.net/server/kb/how-to-articles/devolutions-server-docker-deployment/advanced-docker-configuration/)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.devolutions.net/server/knowledge-base/how-to-articles/devolutions-server-docker-deployment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.