Install on macOS and Windows with Docker

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

This page describes how to install Aerospike Database on macOS and Windows with Docker. Aerospike Database runs natively on 64-bit Linux, and with Docker you can also deploy it on macOS and Windows. Aerospike provides container images for x86_64 processors and 64-bit ARM (Apple M series) processors.

Install with Docker Desktop

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

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.
Terminal
```
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.
Start the Aerospike container.
Terminal
```
docker run -d --name aerospike -p 3000-3002:3000-3002 aerospike/aerospike-server-enterprise
```
EE’s evaluation features are unlocked in its included feature-key file. If Aerospike issued you a feature-key file, such as a trial or production key, set an environment variable to its base64-encoded contents and pass it to the Docker image. CE does not use a feature-key file.
Terminal
```
export FEATKEY=$(base64 < ~/evaluation-features.conf | tr -d '\n')

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.

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   0.0.0.0:3000-3002->3000-3002/tcp   aerospike

Test your Docker installation

Before you start developing clients, use Aerospike Quick Look (AQL), Aerospike’s command-line data browser, to insert and read records to verify that the database is running.

Run the following command to install and run the Aerospike tools container image and AQL tool:
Terminal
```
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 Database container with the docker inspect command.

After you run the command, the aql command prompt appears.
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.

Note
AQL does not require a semicolon to terminate a single command, but you can use semicolons to combine multiple commands. The following example executes three record inserts in a single terminal command.
AQL
```
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')
```

Query the database:

select * from test.birds

AQL output

+----+-----------------+----------------+
| PK | location        | species        |
+----+-----------------+----------------+
| 3  | "Palo Alto"     | "snowy plover" |
| 2  |                 | "seagull"      |
| 1  | "Mountain View" | "scrub jay"    |
+----+-----------------+----------------+
3 rows in set (0.049 secs)

Create a shared directory (optional)

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

Create the /opt/aerospike/etc directory on your local machine.
Start Docker Desktop.
Click the Settings gear icon in the upper right corner of the window.
Click Resources, then click File sharing in the sidebar.
In the Virtual file shares section, add /opt/aerospike/etc to the empty folder path at the bottom of the list of shared folders.
Click the plus icon to the right of the new folder path.
Click Apply & restart.

Run a multi-node cluster

The Docker image includes a feature-key file that supports only one node. If you do not pass a custom configuration file, the image uses replication-factor 1 and does not configure mesh seeds.

To run multiple nodes, you need a feature-key file that permits more than one node and configuration files that define mesh seeds and replication. You can request a trial key from the Try now page.

When you start the container with --config-file, the image ignores the FEATURE_KEY_FILE environment variable. Set feature-key-file in your configuration file instead.

Remove the single-node container if it’s running, load your feature-key file into a variable, and create a directory and a Docker network for the nodes.

docker rm -f aerospike
export FEATKEY=$(base64 < ~/evaluation-features.conf | tr -d '\n')
mkdir -p "$HOME/aerospike-cluster"
docker network create aerospike-net

Create a configuration file for each node. The files differ only in access-port, which exposes the nodes on host ports 3000, 3100, and 3200. Each node joins the cluster through aerospike-1.

for i in 1 2 3; do
cat > "$HOME/aerospike-cluster/aerospike-$i.conf" <<EOF
service {
    feature-key-file env-b64:FEATURES
    cluster-name docker
}

logging {
    console {
        context any info
    }
}

network {
    service {
        address any
        port 3000
        access-address 127.0.0.1
        access-port $((2900 + i * 100))
    }

    heartbeat {
        mode mesh
        port 3002
        mesh-seed-address-port aerospike-1 3002
        interval 150
        timeout 10
    }

    fabric {
        port 3001
    }
}

namespace test {
    replication-factor 2
    storage-engine device {
        file /opt/aerospike/data/test.dat
        filesize 4G
    }
}
EOF
done

Start the nodes, beginning with aerospike-1.

for i in 1 2 3; do
docker run -d --name aerospike-$i --network aerospike-net -p $((2900 + i * 100)):3000 \
  -e "FEATURES=$FEATKEY" \
  -v "$HOME/aerospike-cluster:/opt/aerospike/etc" \
  aerospike/aerospike-server-enterprise \
  --config-file /opt/aerospike/etc/aerospike-$i.conf
done

After about 10 seconds, verify that the log reports CLUSTER-SIZE 3.
Terminal
```
docker logs aerospike-1 2>&1 | grep CLUSTER-SIZE | tail -1
```

Clients on your machine connect to 127.0.0.1:3000 and discover the other nodes automatically. Because the nodes advertise 127.0.0.1 as their access-address, clients in separate Docker containers, such as the AQL container in Test your Docker installation, cannot reach them with this configuration.