---

SingleStore DB can handle many workloads completely for free, and it’s very easy to get started. The free edition of SingleStore DB can scale up to 128GB of RAM (total) and 32 CPU cores – enough power to process billions of records on just a few virtual machines.

See the video version of this guide.

This guide walks you through setting up a “cluster in a box”/single machine deployment using the SingleStore DB free license. It’s quick and easy. That said, with a little more work, you can use that same license to deploy on a small group of machines (multi-node cluster) for free. For more information about deploying a multi-node cluster, see this deployment guide.

Overview

This guide shows you how to quickly build a single-instance cluster running on Docker Desktop, on a laptop computer, for free. You’ll need a machine with at least 8GB RAM and 4 CPUs. This is ideal for quickly provisioning a system to understand the capabilities of SingleStore DB’s SQL engine. Everything described in this guide will be running on your computer, and by using a Docker container, you do not need to install or configure much of SingleStore DB to get it running.

Here’s the process, with each step outlined below:

1. Get a free license
2. Install Docker Desktop
3. Create a Docker Compose file
4. Start the cluster through Docker
5. Start SingleStore DB Studio

After following these steps, you’ll have a bare-bones cluster running on your machine. After that, check out some possible next steps.

	Cluster-in-a-box	Multi-node Cluster
Hardware	Laptop computer	Many hefty servers
Best use-cases	* Try out SingleStore DB * Test SingleStore DB capabilities * Prototyping	* Proof of concept (PoC) * Production workloads * High availability
Cost	Free up to four nodes with 32GB RAM each, and with community support	Free up to four nodes with 32GB RAM each, and with community support

For more information about deploying a multi-node cluster, see this deployment guide.

Sign Up for SingleStore DB

To get a free license for SingleStore DB:

1. Register at singlestore.com/download and click the link in the confirmation email.
2. Go to the SingleStore Customer Portal at portal.singlestore.com and log in.
3. Click Licenses and you’ll see your license for running SingleStore DB for free. This license never expires, and is good for clusters up to four machines and up to 128GB of combined RAM. This is definitely not the license you’ll want for a production cluster, but it’s great for “kick the tires” scenarios.
4. Note this license key. You’ll need to copy/paste it into place next.

Install Docker Desktop

The first step in getting our cluster running in Docker Desktop is to get Docker Desktop installed. If you already have a recent version of Docker Desktop, you need only ensure you’re in Linux containers mode.

Docker’s install requirements are quite specific, though most modern mid-range systems will do. Docker Desktop for Windows runs a Linux VM in Hyper-V, and Hyper-V requires Windows 10 Pro or Enterprise. Docker Desktop for Mac runs a Linux VM in xhyve, and requires a 2010 or newer model with macOS 10.13 or better.

To install Docker Desktop, go to Docker Hub and choose the Docker Desktop version for your operating system. The download will require you to create a free account. Run the downloaded installer and accept all the defaults.

Windows containers can run SingleStore DB too.

Note for Windows users: If you are doing a fresh install, ensure you choose “Linux Containers” mode. If you installed Docker previously, ensure you’re running in Linux Containers mode. Right-click on the Docker whale icon in the system tray (bottom-right by the clock), and choose Switch to “Linux Containers”. If it says “Switch to Windows Containers”, you’re already in Linux Containers mode.

Create a Docker Compose File

A docker-compose.yaml file gives Docker Desktop instructions to spin up one or more containers together. It’s a great way to capture all the docker pull, docker build, and docker run details. This file doesn’t replace Dockerfile but rather makes it much easier to use the parameters.

We’ll use the singlestore/cluster-in-a-box image built by SingleStore DB and available on Docker Hub. Pre-installed in this image is the SingleStore DB database engine and SingleStore DB Studio. The minimum system requirements are disabled in this “cluster-in-a-box” configuration.

Create an empty directory and create a file named docker-compose.yaml inside. Open this file in your favorite code editor and paste in this content:

version: '2'

services:
  memsql:
    image: 'singlestore/cluster-in-a-box'
    ports:
      - 3306:3306
      - 8080:8080
    environment:
      LICENSE_KEY: ${LICENSE_KEY}
      START_AFTER_INIT: 'Y'

A YAML file is a text file that’s great for capturing our architecture setup. As with Python source code, white space is significant. YAML uses two spaces, not tabs. Double-check the YAML file to ensure each section is indented with exactly two spaces. If you have more or fewer spaces, or if you’re using tabs, you’ll get an error on startup.

Here are the sections in the docker-compose.yaml file:

1. Using Docker Compose syntax Version 2.
2. The services array lists all the containers that will start up together. A single container is defined here, named memsql, which uses the singlestore/cluster-in-a-box image built by SingleStore.
3. The Ports section identifies inbound traffic that will route into the container. Open port 3306 for the database engine and port 8080 for SingleStore DB Studio. If either of these ports are in use on your machine, change only the left port. For example, to connect from outside Docker to the database on port 3307 use 3307:8080.
4. The first environment variable, START_AFTER_INIT, exists for legacy reasons. Without this environment variable, the container will spin up, initialize the cluster, and immediately stop. This is great for debugging, but not the point of this guide.
5. The second environment variable, LICENSE_KEY, is the placeholder for the license you got from portal.singlestore.com. Don’t copy the license key into place here – you’ll accidentally leak secrets into source control. Instead, this syntax notes that you’ll reference an environment variable set in the terminal.

In time, you could easily add you application, business intelligence (BI) dashboard, and other resources to this file. If you have an existing docker-compose.yaml file, you can copy that content into place here too.

Save the file, and you’re ready to launch Docker.

Start the SingleStore DB Cluster

Open a new terminal window in the same directory as the docker-compose.yaml file. This could be Powershell, a command prompt, or a regular terminal.

First, set the license key as an environment variable. Copy the license from portal.singlestore.com in the Licenses tab, and create an environment variable in the terminal:

Command prompt:

set LICENSE_KEY=paste_license_key_here

Powershell:

$env:LICENSE_KEY = 'paste_license_key_here'

Mac/Linux/Git Bash:

export LICENSE_KEY=paste_license_key_here

Paste your actual license key in place of paste_license_key_here. It’s a very long string and probably ends with ==.

Next, type this in the shell:

docker-compose up

This tells Docker to pull or build all the images, start up all the containers in our docker-compose.yaml file, and stream the console output from each container to our terminal.

If you get an error starting the cluster, double-check that the license key is correct and that Docker is running. If you get an image pull failure, ensure your network connection is working as expected. To retry, type Ctrl-C in the terminal, then type:

docker-compose down
docker-compose up

Congratulations! You’ve launched a cluster. Now it’s time to dive in and start using it.

Start SingleStore DB Studio

Now that SingleStore DB is running in Docker, open a browser to http://localhost:8080 to launch SingleStore DB Studio. Click on the local cluster, enter a username of root, leave the password blank, and log in.

On this main dashboard screen, you can see the health of the cluster. Note that this is a two-node cluster. Clicking on Nodes on the left, you see one node is a leaf node, one is an aggregator node, and they’re both running in the same container. In production, you would want more machines running together to support production-level workloads and to provide high availability.

Click on the SQL Editor page. Copy and paste the following set of commands into the Query window. Then, highlight each individual command and click the Execute button in the top-right to run it. Continue to highlight and execute each command until all commands have been executed.

CREATE DATABASE hellomemsql;

USE hellomemsql;

CREATE TABLE test (
  message text NOT NULL
);

INSERT INTO test (message) VALUES ('this is a sample message');

SELECT * FROM test;

For more details on SingleStore DB Studio, check out the documentation or watch the SingleStore DB Studio tour video.

Next Steps

SingleStore DB is now ready for all your “kick the tires” tasks. Being able to run these tasks from such a simple setup is a real time-saver. However, don’t expect the same robustness or performance as you would have with a full install on a full hardware configuration.

Load Data

SingleStore DB supports a wide variety of data-loading scenarios, including ingesting from Kafka, S3, Spark, or other data sources. In general we recommend getting started via Pipelines.

• Streaming data loads: Pipelines
• One-time data load: LOAD DATA
• app load: DML overview (page explaining our DML at a high level)

Read Data, Integrate, and Connect

SingleStore DB supports querying data via any driver or third-party tool which supports the MySQL wire protocol. This makes it super easy to get started. In general, if your tool of choice supports MySQL then it also supports SingleStore DB!

Hook up your analytics dashboard to SingleStore DB.

Add your application to the docker-compose.yaml file and connect it to SingleStore DB using any MySQL connector.

Get Help

Reach out for help on the SingleStore Forums.

Learn more about the product and features in the documentation.