The SingleStore Dev Image is the fastest way to develop with SingleStore on your laptop or in a CI/CD environment (including GitHub Actions). This Docker image is not supported for production workloads or benchmarks so please keep this in mind when using it.
If you have any questions or issues, please file an issue on the GitHub repo or our forums.
- How to run the Docker image?
- How to open a SQL shell?
- How to access the Studio UI?
- Where can I learn how to use SingleStore?
- How to access the Data API?
- How to use WebAssembly (Wasm) backed functions?
- How to use Docker volumes for persistent storage?
- How to initialize this container with a SQL file?
- How to set SingleStore global variables?
- How to use a specific SingleStore version?
- How to use this container in a CI/CD environment?
- How to upgrade from singlestore/cluster-in-a-box?
- Apple silicon performance notes
This Docker image allows a cluster to be deployed in a self-contained container without the need for a license.
When running a Docker container on a machine with:
- More than 32 cores, include the
--cpus=32option. - More than 128GB of RAM, include the
--memory=128goption.
Note
SingleStore recommends using an explicit image version tag whenever possible from the list of image tags and/or the changelog.
See next section for Apple silicon instructions.
docker run \
-d --name singlestoredb-dev \
-e ROOT_PASSWORD="YOUR SINGLESTORE ROOT PASSWORD" \
-p 3306:3306 -p 8080:8080 -p 9000:9000 \
ghcr.io/singlestore-labs/singlestoredb-dev:latestIf you want to configure a specific license, simply pass it as an environment variable:
docker run \
-d --name singlestoredb-dev \
-e ROOT_PASSWORD="YOUR SINGLESTORE ROOT PASSWORD" \
-e SINGLESTORE_LICENSE="YOUR SINGLESTORE LICENSE" \
-p 3306:3306 -p 8080:8080 -p 9000:9000 \
ghcr.io/singlestore-labs/singlestoredb-dev:latestIf you want to use Kai (API for MongoDB clients), set ENABLE_KAI=1 and expose port 27017:
docker run \
-d --name singlestoredb-dev \
-e ROOT_PASSWORD="YOUR SINGLESTORE ROOT PASSWORD" \
-e ENABLE_KAI=1 \
-p 3306:3306 -p 8080:8080 -p 9000:9000 -p 27017:27017 \
ghcr.io/singlestore-labs/singlestoredb-dev:latestThen connect with, for example:
mongosh "mongodb://root:YOUR SINGLESTORE ROOT PASSWORD@localhost:27017/?authMechanism=PLAIN&loadBalanced=true"Note
The latest SingleStore Dev Image uses AlmaLinux 10 as the base OS, which relies on the x86‑64‑v3 instruction set. This version should work as expected on:
- Apple silicon Macs running macOS 26
- Intel Macs running macOS 15 (Sequoia) and macOS 26 (Tahoe)
The version of Rosetta on Apple silicon Macs running macOS 15 does not support the x86‑64‑v3 instruction set. When attempting to run the latest SingleStore Dev Image on these Macs, a
Fatal glibc error: CPU does not support x86-64-v3message is displayed.To remedy this, either:
- Upgrade your Apple silicon Mac to macOS 26
- Use SingleStore Helios for development
First, make sure you are using Docker Desktop which supports the latest virtualization technology on Apple silicon.
Second, you must enable "Use Virtualization framework" and "Use Rosetta for x86_64/amd64 emulation on Apple Silicon" in Docker Desktop preferences. If you do not do this, SingleStore will run very slowly and consume a lot of power on your Mac. You can find these settings under Docker Desktop > Preferences > General.
Third, run the following command to start SingleStore. Note the --platform linux/amd64 instruction which is required when running on Apple silicon.
docker run \
-d --name singlestoredb-dev \
-e ROOT_PASSWORD="YOUR SINGLESTORE ROOT PASSWORD" \
--platform linux/amd64 \
-p 3306:3306 -p 8080:8080 -p 9000:9000 \
ghcr.io/singlestore-labs/singlestoredb-dev:latestWindows PowerShell and Command Prompt (CMD) work best if you run the command on a single line. Alternatively you can use backticks for multi-line strings in PowerShell. Either way, the following single-line version of the command will work on Windows.
docker run -d --name singlestoredb-dev -e ROOT_PASSWORD="YOUR SINGLESTORE ROOT PASSWORD" -p 3306:3306 -p 8080:8080 -p 9000:9000 ghcr.io/singlestore-labs/singlestoredb-dev:latestThis image includes a shell which you can run interactively using docker exec.
The following command will prompt you for the root password.
docker exec -it singlestoredb-dev singlestore -pYou can also provide the root password at the command line immediately after the -p flag like so:
docker exec -it singlestoredb-dev singlestore -pYOUR_ROOT_PASSWORDYou can also connect to SingleStore using any MySQL compatible client on your own machine using the following connection details:
| Key | Value |
|---|---|
| Host | 127.0.0.1 |
| Port | 3306 |
| Username | root |
| Password | YOUR_ROOT_PASSWORD |
The Studio UI is a convenient way to connect to SingleStore and run queries via a browser-based UI. The UI runs by default on port 8080 in the container. Assuming that you have forwarded port 8080 to your local machine, you can access the UI at http://localhost:8080.
You will see a login screen when you open the UI. Use the username root and the associated password you set when starting the container.
Now that you have SingleStore running, please check out the following sections of our official documentation for guides on what to do next.
In addition to supporting the MySQL protocol, SingleStore also has a JSON over HTTP protocol called the Data API which you can access at port 9000 in the container. Assuming that you have forwarded port 9000 to your local machine, the following curl command demonstrates how you can use the Data API:
~ âžś curl -s -XPOST -H "content-type: application/json" -d '{ "sql": "select 1" }' root:YOUR_ROOT_PASSWORD@localhost:9000/api/v1/query/rows
{
"results": [
{
"rows": [
{
"1": 1
}
]
}
]
}Note
For more information on how to use the Data API please visit the documentation.
The Code Engine feature in SingleStore supports creating functions (UDFs and TVFs) using code compiled to WebAssembly (Wasm). This feature supports any language that can compile to the Wasm core specification, which allows you to create UDFs in a language of your choice using existing code libraries and run them in a sandboxed environment for enhanced security. It uses a linear memory model and provides hard memory protection boundaries.
This Docker image has Wasm functions enabled by default. You can learn how to compile and load Wasm UDFs and UDAs into SingleStore in our docs.
Note
If you are specifying a Singlestore version at runtime, your data will always be overwritten when the container restarts each time, as the container will always attempt to re-download and re-initialize the installed version on each run.
To get around this, build a custom image with your specific version.
docker run \
-d --name singlestoredb-dev \
-e ROOT_PASSWORD="YOUR ROOT PASSWORD" \
-p 3306:3306 -p 8080:8080 -p 9000:9000 \
-v my_cool_volume:/data \
ghcr.io/singlestore-labs/singlestoredb-devAfter creating the container with a volume, you can re-create the container using the same volume to keep your data around. This can be used to upgrade SingleStore to new versions without losing your data. Keep in mind that SingleStore does not support downgrading. Make sure to take a backup of the volume before running the upgrade.
Note
In order to mount a host volume to the
/datadirectory, you will need tochownthe volume toUID=999andGID=998before mounting it. The volume will be initialized automatically if empty. Host volumes are only supported by the/datadirectory.
This Docker image has a number of volume mount points in addition to /data. The following table outlines each of the mount points along with roughly their contents:
| Mount Path | Description |
|---|---|
/data |
All of the data, config, and cache for the SingleStore cluster. |
/logs |
All of the tracelog files containing information that can help debug the cluster or observe its current behavior. |
/server |
The installation directory containing server binaries and other installation state. |
When this Docker image starts for the first time, it checks to see if an init.sql file exists in its filesystem. The default location is /init.sh, but it can be customized via the INIT_SQL environment variable. If init.sql is found, the container will run it against the database as soon as SingleStore is ready.
One way to do this is by mounting an init.sql from your machine into the container using the -v flag. Here is an example of doing this:
docker run \
-d --name singlestoredb-dev \
-e ROOT_PASSWORD="YOUR ROOT PASSWORD" \
-p 3306:3306 -p 8080:8080 -p 9000:9000 \
-v ${PWD}/test/init.sql:/init.sql \
ghcr.io/singlestore-labs/singlestoredb-devReplace ${PWD}/test/init.sql with an absolute path to the SQL file with which to initialize SingleStore.
Note
The
/init.sqlfile will only be run once. To run it again, you will need to delete the file/data/.init.sql.doneand then restart the container.
SingleStore can be configured through the use of global variables which you can find in our documentation. These variables can be set using environment variables when running the SingleStore Dev Image using the prefix SINGLESTORE_SET_GLOBAL_.
For example, if you want to set default_partitions_per_leaf to 1, you would do this:
docker run \
-d --name singlestoredb-dev \
-e ROOT_PASSWORD="YOUR ROOT PASSWORD" \
-e SINGLESTORE_SET_GLOBAL_DEFAULT_PARTITIONS_PER_LEAF=1 \
-p 3306:3306 -p 8080:8080 -p 9000:9000 \
ghcr.io/singlestore-labs/singlestoredb-devMultiple environment variables can be specified if you want to configure multiple global variables in SingleStore.
If you specify a variable which is not supported by SingleStore, the image will fail to start. You can see the full error message by inspecting the failed Docker container's logs using docker log.
By default, the SingleStore Dev Image uses the latest version of SingleStore available. If you would prefer to use another SingleStore version, you will need to either build a custom version of this image or specify the version at runtime by following the tutorials below.
You can use the version numbers in the first column of the following table in order to run a specific version of SingleStore. If you want to use a particular patch version, just specify that version instead.
SINGLESTORE_VERSION |
Description | |
|---|---|---|
| 9.0 | SingleStore Self-Managed 9.0, see release log for latest version | changelog |
| 8.9 | SingleStore Self-Managed 8.9, see changelog for latest version | changelog |
| 8.7 | SingleStore Self-Managed 8.7, see changelog for latest version | changelog |
| 8.5 | SingleStore Self-Managed 8.5, see changelog for latest version | changelog |
| 8.1 | SingleStore Self-Managed 8.1, see changelog for latest version | changelog |
| 8.0 | SingleStore Self-Managed 8.0, see changelog for latest version | changelog |
| 7.8 | SingleStore Self-Managed 7.8, see changelog for latest version | changelog |
| 7.6 | SingleStore Self-Managed 7.6, see changelog for latest version | changelog |
The script /scripts/switch-version.sh can be used to easily build a custom version of this image. The fastest way to do this is using Docker build like so:
cat <<EOF | docker build -f - -t singlestoredb-dev:custom .
FROM ghcr.io/singlestore-labs/singlestoredb-dev
RUN /scripts/switch-version.sh SINGLESTORE_VERSION SINGLESTORE_LICENSE
EOFMake sure to replace SINGLESTORE_VERSION and SINGLESTORE_LICENSE with the SingleStore version you want to use (see table above) as well as your license key. After running this command, you will have a new Docker image called singlestoredb-dev:custom with the specific version of SingleStore installed and ready to use.
In order to use a specific version of SingleStore at runtime, you can start the Docker container with the SINGLESTORE_VERSION environment variable set.
Warning
This method will result in the container taking much longer to start (roughly a minute) because it has to download and install SingleStore each time. For this reason, SingleStore recommends building a custom version of this Docker image using the instructions above.
Here is an example of using the SINGLESTORE_VERSION environment variable to run SingleStore 9.0:
docker run \
-d --name singlestoredb-dev \
-e ROOT_PASSWORD="YOUR ROOT PASSWORD" \
-e SINGLESTORE_VERSION="9.0" \
-p 3306:3306 -p 8080:8080 -p 9000:9000 \
ghcr.io/singlestore-labs/singlestoredb-devNote
You can mount
/serverinto a Docker volume to preserve the installed SingleStore server binaries if you are unable to use the custom image method. This will increase subsequent startup performance at the expense of complexity.
This Docker image defines a healthcheck which runs every 5 seconds. Any CI/CD system or container runtime which respects the healthcheck should automatically wait for SingleStore to be running and healthy.
Here is an example workflow which runs SingleStore as a container service and queries it from the job.
name: my-workflow
on: push
jobs:
my-job:
runs-on: ubuntu-latest
needs: build-image
services:
singlestoredb:
image: ghcr.io/singlestore-labs/singlestoredb-dev
ports:
- 3306:3306
- 8080:8080
- 9000:9000
env:
ROOT_PASSWORD: test
# Optional:
# SINGLESTORE_LICENSE: ${{ secrets.SINGLESTORE_LICENSE }}
steps:
- name: sanity check using mysql client
run: |
mysql -u root -ptest -e "SELECT 1" -h 127.0.0.1Here is an example workflow which runs SingleStore as a service and queries it from the job. Unfortunately GitLab does not support Docker healthchecks for services, so additional logic must be added to wait for SingleStore to be ready. There is a closed GitLab issue with more information.
Note
You can add your SingleStore license key to GitLab secrets under the key
SINGLESTORE_LICENSE.
image: debian
stages:
- test
variables:
ROOT_PASSWORD: test
# Optional:
# SINGLESTORE_LICENSE: $SINGLESTORE_LICENSE
testing:
stage: test
services:
- name: ghcr.io/singlestore-labs/singlestoredb-dev:latest
alias: singlestoredb-dev
script:
- apt update
- apt install -y mariadb-client curl
- curl -sI localhost:8080 --retry 30 --retry-connrefused --retry-delay 1
- mysql -u root -ptest -h singlestoredb-dev -e "create database foo"
- mysql -u root -ptest -h singlestoredb-dev -e "create table foo.bar (id int)"
- mysql -u root -ptest -h singlestoredb-dev -e "insert into foo.bar values (1),(2),(3)"
- mysql -u root -ptest -h singlestoredb-dev -e "select * from foo.bar"Before this image was created, there was another Docker image called singlestore/cluster-in-a-box (CIAB). The docker run command for the CIAB image looked something like this:
docker run -i --init \
--name singlestore-ciab \
-e LICENSE_KEY=${LICENSE_KEY} \
-e ROOT_PASSWORD=${ROOT_PASSWORD} \
-p 3306:3306 -p 8080:8080 \
singlestore/cluster-in-a-boxThe differences between the CIAB image and the Dev image are the following:
- The Dev image no longer needs to be initialized before you can use it
- Startup time is much better - roughly 5 seconds with the Dev image versus a minute with the CIAB image
- The Data API and External Functions features are enabled by default in the Dev image
- Upgrade between versions is supported and tested with the Dev image (downgrades are not supported)
- The Dev image is distributed through the GitHub Container Repository rather than the Docker Hub
SingleStore recommends using the Dev image unless you need to run earlier versions of SingleStore that have not been released as a singlestoredb-dev-image.
Many of SingleStore's performance optimizations are disabled in order to support running on Apple silicon. This can result in unexpectedly poor performance, especially during recovery (restarting SingleStore) and when running queries for the first time.
To tune this performance impact to be either faster or slower, you can change the number of cores and amount of RAM allocated to the Docker virtual machine by following the documentation here.