# How to Set Up a Dolt Server: Complete Configuration Guide

> Learn how to set up a Dolt server with this complete guide. Configure your Dolt server using Docker, the CLI, or from source for seamless data management.

- Repository: [DoltHub/dolt](https://github.com/dolthub/dolt)
- Tags: how-to-guide
- Published: 2026-03-14

---

**You can set up a Dolt server by running the official Docker image `dolthub/dolt-sql-server`, executing the `dolt sql-server` CLI command, or building from source, with all runtime behavior controlled via a YAML configuration file parsed into `servercfg.YAMLConfig`.**

Dolt is a SQL database with Git-like versioning capabilities from the **dolthub/dolt** repository. Setting up a Dolt server provides a MySQL-compatible endpoint that stores data in versioned Dolt repositories, allowing any standard MySQL client to connect while maintaining full version control over your schema and data.

## Installation Methods

The Dolt server can be deployed via Docker, compiled from source, or installed as a local binary. Each method exposes the same MySQL-compatible wire protocol implemented in the `go-mysql-server` library.

### Docker (Recommended)

The fastest way to set up a Dolt server uses the official `dolthub/dolt-sql-server` image. This container runs `dolt sql-server --host 0.0.0.0 --port 3306` by default according to [`docker/serverREADME.md`](https://github.com/dolthub/dolt/blob/main/docker/serverREADME.md) (lines 78-81).

Pull and run the server with environment variables:

```bash

# Pull the latest image

docker pull dolthub/dolt-sql-server:latest

# Run the server exposing port 3306

docker run -d \
  -e DOLT_ROOT_PASSWORD=secret2 \
  -e DOLT_ROOT_HOST=% \
  -p 3307:3306 \
  dolthub/dolt-sql-server:latest

```

### Build from Source

To build the server binary from the source code, clone the repository and use the multi-stage Dockerfile located at `docker/serverDockerfile` (lines 12-40):

```bash
git clone https://github.com/dolthub/dolt.git
cd dolt

docker build -f docker/serverDockerfile \
  --build-arg DOLT_VERSION=source \
  -t dolt-sql-server:source .

```

### Local Binary Installation

Install the CLI using Go 1.25 or later, then invoke the server directly:

```bash
go install ./cmd/dolt

dolt sql-server --host 0.0.0.0 --port 3306

```

The CLI command structure is documented in the top-level [`README.md`](https://github.com/dolthub/dolt/blob/main/README.md) (lines 31-43).

## Configuring the Server

Runtime configuration is defined in a **YAML** file that the server parses into the `servercfg.YAMLConfig` struct defined in [`go/libraries/doltcore/servercfg/yaml_config.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/servercfg/yaml_config.go) (lines 15-20). The default location inside containers is `/etc/dolt/servercfg.d/*.yaml` as noted in [`docker/serverREADME.md`](https://github.com/dolthub/dolt/blob/main/docker/serverREADME.md) (lines 46-52).

A minimal configuration specifies the listener, user credentials, and behavior:

```yaml
listener:
  host: 0.0.0.0
  port: 3306
  socket: /var/lib/dolt/dolt.sock

user:
  name: root
  password: secret2

behavior:
  read_only: false
  autocommit: true

```

The `YAMLConfig` struct maps fields such as `ListenerConfig.HostStr` and `UserConfig.Name` to these YAML keys (lines 82-90 in [`yaml_config.go`](https://github.com/dolthub/dolt/blob/main/yaml_config.go)).

### Mounting Config in Docker

Persist data and supply custom configuration by mounting host directories:

```bash
mkdir -p $HOME/dolt-data $HOME/dolt-config

cat > $HOME/dolt-config/server.yaml <<'EOF'
listener:
  host: 0.0.0.0
  port: 3306
user:
  name: admin
  password: strongpwd
behavior:
  read_only: false
EOF

docker run -d \
  -v $HOME/dolt-data:/var/lib/dolt \
  -v $HOME/dolt-config:/etc/dolt/servercfg.d \
  -p 3307:3306 \
  dolthub/dolt-sql-server:latest

```

## Connecting to the Server

Any MySQL-compatible client can connect to Dolt because it implements the same wire protocol.

Connect using the MySQL CLI:

```bash
mysql -h 127.0.0.1 -P 3307 -u root -psecret2

```

Or connect via Go using the `go-sql-driver`:

```go
import (
    "database/sql"
    _ "github.com/go-sql-driver/mysql"
)

func main() {
    dsn := "root:secret2@tcp(127.0.0.1:3307)/mydb"
    db, _ := sql.Open("mysql", dsn)
    rows, _ := db.Query("SELECT * FROM my_table")
    // handle rows...
}

```

This connection pattern is verified in the integration tests at [`integration-tests/go-sql-server-driver/main_test.go`](https://github.com/dolthub/dolt/blob/main/integration-tests/go-sql-server-driver/main_test.go) (lines 67-73).

## Advanced Configuration Options

The `servercfg.YAMLConfig` struct supports enterprise features via additional YAML stanzas:

| Feature | Configuration Method | Source Reference |
|---------|---------------------|------------------|
| **TLS / Secure Transport** | Set `tls_key`, `tls_cert`, and `ca_cert` under the `listener` key. Set `require_secure_transport: true` to enforce TLS. | `ListenerYAMLConfig` fields in [`yaml_config.go`](https://github.com/dolthub/dolt/blob/main/yaml_config.go) (lines 90-98) |
| **Read-Only Mode** | Set `behavior.read_only: true` to prevent write operations. | `BehaviorYAMLConfig.ReadOnly` (lines 54-55) |
| **Auto Garbage Collection** | Configure `behavior.auto_gc_behavior` with `enable: true` and `archive_level: 1`. | `AutoGCBehaviorYAMLConfig` (lines 71-76) |
| **Prometheus Metrics** | Populate the `metrics` section with host, port, labels, and optional TLS settings. | `MetricsYAMLConfig` (lines 14-20) |
| **Cluster Replication** | Provide a `cluster` stanza defining standby replicas and remotes API configuration. | `ClusterYAMLConfig` (lines 47-56) |

## Summary

- **Dolt server** provides a drop-in MySQL replacement that stores data in Git-style versioned repositories.
- Deployment options include the **Docker image** `dolthub/dolt-sql-server`, building from the **Dockerfile** at `docker/serverDockerfile`, or running the **binary** via `dolt sql-server`.
- Configuration is managed through a **YAML file** parsed into `servercfg.YAMLConfig` located by default at `/etc/dolt/servercfg.d/*.yaml`.
- The server supports **TLS encryption**, **read-only mode**, **auto-GC**, **Prometheus metrics**, and **cluster replication** through structured configuration keys.
- Any standard **MySQL client** can connect using TCP or Unix sockets.

## Frequently Asked Questions

### What is the default port for a Dolt server?

The Dolt server listens on **port 3306** by default, matching MySQL conventions. When running in Docker, you can map this to any host port (e.g., `-p 3307:3306`) to avoid conflicts with existing MySQL instances. The port is defined in the `listener.port` field of the YAML configuration or via the `--port` CLI flag.

### How do I persist Dolt databases when using Docker?

Mount a host directory to `/var/lib/dolt` inside the container to persist the `.dolt` repositories. For example, `-v $HOME/dolt-data:/var/lib/dolt` ensures that databases survive container restarts. This volume contains the versioned data files that Dolt manages.

### Can I use existing MySQL tools and drivers with Dolt?

Yes. Dolt implements the **MySQL wire protocol** using the `go-mysql-server` library, making it compatible with the `mysql` CLI, MySQL Workbench, JDBC drivers, and Go's `database/sql` package with the `go-sql-driver/mysql` driver. Connection strings and authentication follow standard MySQL formats.

### Where does Dolt look for the server configuration file?

Inside the official Docker container, Dolt automatically loads any file matching `/etc/dolt/servercfg.d/*.yaml`. For local binary installations, pass the config path explicitly using `dolt sql-server --config server.yaml`. The configuration is unmarshaled into the `YAMLConfig` struct defined in [`go/libraries/doltcore/servercfg/yaml_config.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/servercfg/yaml_config.go).