Skip to main content

Install on macOS and Windows

Aerospike Database runs natively on 64-bit Linux, and with Docker you can deploy Aerospike on macOS and Windows. Aerospike provides container images for x86_64 processors or, on server 6.2 and later, 64-bit ARM processors, such as Apple M1-based laptops.

A convenient way to run Aerospike on macOS and Windows is on Docker Desktop. The following steps describe how to download and set up Docker Desktop.

  1. Pull the Docker image:

    docker pull aerospike/aerospike-server-enterprise
  2. Start an Aerospike container. In Aerospike server 6.1 and later, Aerospike Database Enterprise Edition (EE) starts in a single-node cluster evaluation mode, with all enterprise features available:

    docker run -d --name aerospike -p 3000-3002:3000-3002 aerospike/aerospike-server-enterprise

    Alternatively, you can provide your own feature-key file:

    FEATKEY=$(base64 ~/evaluation-features.conf)

    docker run -d -e "FEATURES=$FEATKEY" -e "FEATURE_KEY_FILE=env-b64:FEATURES" --name aerospike -p 3000-3002:3000-3002 aerospike/aerospike-server-enterprise

    The command uses these options:

    • -d runs the container in detached mode.
    • --name assigns a name to the container.
    • -e "FEATURES=$FEATKEY" sets a container-side environment variable FEATURES with the base64-encoded feature-key file.
    • -e "FEATURE_KEY_FILE=env-b64:FEATURES" sets the feature-key-file config param to the value of the container-side var FEATURES.
    • -p publishes the container's ports to the host.
    • aerospike/aerospike-server-enterprise specifies the name of the image.

    Refer to the Docker run reference for more information.

    For more information on the Aerospike EE image, refer to aerospike/aerospike-server-enterprise on Docker Hub.

  3. Verify that the container is running:

    Run the docker ps command. Its output should resemble the following:

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

Test that Aerospike is ready for developing clients

Use AQL, Aerospike's command-line data browser, to verify that the database is running by inserting a record into it, and then reading the record. When this succeeds you can download a client library and start developing clients.

On macOS and Linux install Aerospike Tools, then connect to your Aerospike container over its exposed IP address.

Alternatively, run the following command to install the tools container image:

docker pull aerospike/aerospike-tools

Run the following command to start a container and AQL:

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 with the docker inspect command.

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

Run the following example command to create a new record in the default namespace test and a new set demo:

insert into test.demo (PK, tval) values (123, 'test-value')

Query the database:

select * from test.demo

Optional: Prepare a shared directory

Select the tab for your operating system.

Open a terminal and create a directory.


It is a best practice to create the directory /opt/aerospike/etc, because this mirrors the default location for the file in the container.

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.