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 and 64-bit ARM (Apple M series) processors.

Docker Desktop is a convenient way to run the containers. After you have installed Docker Desktop, launch it and execute the following steps.

  1. Pull the Docker image. For this example, we use Aerospike Database Enterprise Edition (EE) because it allows a single-node cluster with all enterprise features for evaluation. See Features and Editions for more information.

    docker pull aerospike/aerospike-server-enterprise

    If you prefer to use the Community Edition (CE), use aerospike/aerospike-server as the source for the pull.

  2. Start the Aerospike container.

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

    Enterprise Edition's evaluation features are unlocked in its included feature-key file. If you have your own feature-key file, set an environment variable with the location of the file and pass it to the docker image:

    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
    • -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 configuration parameter to the value of the container-side variable FEATURES.

    • -p maps ports 3000, 3001, and 3002 of the host machine to ports 3000, 3001, and 3002 inside the Docker container, respectively.

    • aerospike/aerospike-server-enterprise specifies the name of the image.

      See the Docker run reference for more information on the Docker parameters.

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

  3. Verify that the container is running:

    Run docker ps to show all running containers. 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 Aerospike Quick Look (AQL), Aerospike's command-line data browser, to verify that the database is running by inserting and reading records.

  1. 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
  2. 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.

  3. Run the following example commands to create some new records in the default namespace test and a new set birds. In this example, we log bird sightings and their locations.


    Although AQL does not require semicolons, the semicolons here allow you to string together record inserts in a single terminal command. Record operations in production are done with external client libraries.

    insert into test.birds (PK, species, location) values (1, 'scrub jay', 'Mountain View');
    insert into test.birds (PK, species) values (2, 'seagull');
    insert into test.birds (PK, location, species) values (3, 'Palo Alto', 'snowy plover')
  4. Query the database:

    select * from test.birds
    | PK | location | species |
    | 3 | "Palo Alto" | "snowy plover" |
    | 2 | | "seagull" |
    | 1 | "Mountain View" | "scrub jay" |
    3 rows in set (0.049 secs)

Next steps

Optional: Prepare a shared directory

  1. Open a terminal and create a directory.


    The directory /opt/aerospike/etc is the default location for the file in the container. Although not required, creating the same directory structure on your OS can make it easier to keep track of the files.

  2. Share the directory with Docker Desktop.

    1. Start Docker Desktop.
    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.