Skip to main content

Aerospike on Docker

Watch the Setup Video#

Walk Through the Instructions#

You can use Docker Desktop to quickly deploy a single-node Aerospike database in a Docker container. You can then use this deployment for application development with any of Aerospike's client libraries.


Download and install Docker Desktop.


Download a free license for a single node of Aerospike Database Enterprise Edition#

  1. Go to the Aerospike homepage and click the Try Now button in the top-right corner of the homepage.
  2. Fill in the first four fields of the form.
  3. In the Select Trial field, select Aerospike Enterprise Edition.
  4. After reading the license agreement and the privacy policy, click Start My Free Trial.
  5. Check your Inbox for an email from "The Aerospike Team".
  6. In the email, click the link in "Download your evaluation feature key file".
  7. Click the Download icon in the top-right corner of the page to save the file evaluation-features.conf to your system.

Place the license file in a directory to share with Docker#

  1. Open a terminal and create a directory.


    A good practice is to create the directory /opt/aerospike/etc, because this mirrors the default location for the file in the container. To create this directory, use this command:

    sudo mkdir -p /opt/aerospike/etc
  2. Copy evaluation-features.conf into this new directory.

Keep the terminal open for later steps.

Share the directory with Docker Desktop#

  1. Start Docker Desktop, if it is not already running.
  2. Click its icon on the menu bar and select Preferences.
  3. Select Resources > File Sharing.
  4. Click the blue plus icon at the bottom of the list of shared directories.
  5. Navigate to the directory, select it, and click Open.
  6. Click the Apply & Restart button.

After Docker Desktop restarts, you can close the Preferences window.

Use Docker to pull an Aerospike Enterprise Edition image from Docker Hub#

In the terminal, run this command to pull an image of the current version:

docker pull aerospike/aerospike-server-enterprise

Start a container and the database by using this image#

Run the docker run command:

docker run --rm -tid --name aerospike -p 3000:3000 -p 3001:3001 -p 3002:3002 \-v <directory-of-license-file>:/aerospike/etc/ \-e "FEATURE_KEY_FILE=/aerospike/etc/evaluation-features.conf" \-e "NAMESPACE=<name-of-namespace>" aerospike/aerospike-server-enterprise

The command uses these options:

  • --rm -- Removes anonymous volumes associated with the container when the container is removed.
  • -t -- Allocates a pseudo-TTY.
  • -i -- Keep STDIN open, even if it is not attached.
  • -d -- Runs the container in background and prints the container ID.
  • --name -- Assigns a name to the container
  • -p -- Publishes the container's ports to the host.
  • -v <directory-of-license-file>:/aerospike/etc/ -- Bind mounts the shared directory as a volume. Replace <directory-of-license-file> with the path of the directory in which you placed a copy of evaluation-features.conf. /aerospike/etc/ is the path to which the volume is mounted in the container.
  • -e "FEATURE_KEY_FILE=/aerospike/etc/evaluation-features.conf" -- Sets the value of the environment variable to the path of the license file in the volume.
  • -e "NAMESPACE=<name-of-namespace>" -- Optional: Sets the name of the namespace to create in the database. The default is test. If you want to specify a non-default name, replace <name-of-namespace> with the name of your choice. Here are the naming guidelines:
    • Maximum length: 31 bytes.
    • Do not use either a colon (:) or a semicolon (;).
    • Avoid using the reserved word null.
  • aerospike/aerospike-server-enterprise -- Specifies the name of the image.

If you would like to use more options in the docker run command, check out its reference documentation.

Verify that the container is running#

Run the docker ps command.

The output should resemble this:

CONTAINER ID   IMAGE                                   COMMAND                  CREATED          STATUS          PORTS                              NAMESc8456f7dd252   aerospike/aerospike-server-enterprise   "/usr/bin/dumb-init …"   21 seconds ago   Up 15 seconds>3000-3002/tcp   aerospike

What to do next#

You can use AQL, Aerospike's command-line data browser, to check that the database is running by inserting a record into it and then reading the record back. Then, you can download a client library and start developing.

Use Docker to pull an image of the current aerospike-tools package.#

In the terminal, run this command:

docker pull aerospike/aerospike-tools

Start a container and AQL by using this image#

In the terminal, run this command:

docker run -it aerospike/aerospike-tools aql -h  $(docker inspect -f '\{\{.NetworkSettings.IPAddress\}\}' aerospike)

The command invokes AQL in the aerospike/aerospike-tools container, providing AQL's -h option with the IP address of the Aerospike server container by using the docker inspect command.

After you run the command, the aql command prompt appears.

Insert a record into the database#

Issue this statement, where:

  • <name-of-namespace> is the name that you gave to the namespace in the docker run command for starting the database.
  • <name-of-set> is a name to use to create a set within the namespace.
insert into <name-of-namespace>.<name-of-set> (PK, test) values (123, 'test-value')

Query the database#

You can issue a simple select \* statement to read back the record:

select * from <name-of-namespace>.<name-of-set>

Download a client library#

Now that you've verified the database is running, you can download the Aerospike client library of your choice and start developing an application.