Aerospike is a distributed NoSQL database purposefully designed for high performance applications. Aerospike supports key-value and document data models, and has multiple data types including List, Map, HyperLogLog, GeoJSON, and Blob. Aerospike's patented hybrid memory architecture delivers predictable high performance at scale and high data density per node.
- Getting Started
- Connecting to your Aerospike Container
- Customizing the Default Developer Environment
- Advanced Configuration
- Sending telemetry data to Aerospike
- Image Versions
- Building Images
- Reporting Issues
- License
Aerospike Database Community Edition (CE) supports the same developer APIs as Aerospike Database Enterprise Edition (EE), except for durable deletes. They differ in ease of operation and enterprise features, such as compression.
Since server version 6.1, Aerospike EE starts in a single-node cluster evaluation mode, with all its enterprise features available.
Running Enterprise Edition with default evaluation feature key (versions 6.1+).
docker run -d --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-enterpriseRunning Enterprise Edition with a feature key file in a mapped directory:
docker run -d -v DIR:/opt/aerospike/etc/ -e "FEATURE_KEY_FILE=/opt/aerospike/etc/features.conf" --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-enterpriseRunning Enterprise Edition with a feature key file in an environment variable:
FEATKEY=$(base64 ~/Desktop/evaluation-features.conf)
docker run -d -e "FEATURES=$FEATKEY" -e "FEATURE_KEY_FILE=env-b64:FEATURES" --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-enterpriseAbove, DIR is a directory on your machine where you drop your feature key file. Make sure Docker Desktop has file sharing permission to bind mount it into Docker containers.
Running Enterprise Edition for US Federal with default evaluation feature key (versions 6.1+).
docker run -d --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-federalRunning Aerospike Enterprise Edition for US Federal with a feature key file in a mapped directory:
docker run -d -v DIR:/opt/aerospike/etc/ -e "FEATURE_KEY_FILE=/opt/aerospike/etc/features.conf" --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-federalAbove, DIR is a directory on your machine where you drop your feature key file. Make sure Docker Desktop has file sharing permission to bind mount it into Docker containers.
Running Aerospike Enterprise Edition for US Federal with a feature key file in an environment variable:
FEATKEY=$(base64 ~/Desktop/evaluation-features.conf)
docker run -d -e "FEATURES=$FEATKEY" -e "FEATURE_KEY_FILE=env-b64:FEATURES" --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-federalBy using Aerospike Community Edition you agree to the Community License.
Running Aerospike Community Edition:
docker run -d --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-serverYou can use the latest aerospike-tools image to connect to your Aerospike container.
docker run -ti aerospike/aerospike-tools:latest aql -h $(docker inspect -f '{{.NetworkSettings.IPAddress }}' aerospike)
Seed: 172.17.0.2
User: None
Config File: /etc/aerospike/astools.conf /root/.aerospike/astools.conf
Aerospike Query Client
Version 7.0.4
C Client Version 6.0.0
Copyright 2012-2021 Aerospike. All rights reserved.
aql> show namespaces
+------------+
| namespaces |
+------------+
| "test" |
+------------+
[172.17.0.2:3000] 1 row in set (0.002 secs)
OKdocker run -ti aerospike/aerospike-tools:latest asadm -h $(docker inspect -f '{{.NetworkSettings.IPAddress }}' aerospike)
Seed: [('172.17.0.2', 3000, None)]
Config_file: /root/.aerospike/astools.conf, /etc/aerospike/astools.conf
Aerospike Interactive Shell, version 2.10.0
Found 1 nodes
Online: 172.17.0.2:3000
Admin> info
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Network Information (2022-11-01 00:48:05 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Node| Node ID| IP| Build|Migrations|~~~~~~~~~~~~~~~~~~Cluster~~~~~~~~~~~~~~~~~~|Client| Uptime
| | | | |Size| Key|Integrity| Principal| Conns|
172.17.0.2:3000|*BB9020011AC4202|172.17.0.2:3000|E-6.1.0.3| 0.000 | 1|19E628721D9A|True |BB9020011AC4202| 8|00:02:09
Number of rows: 1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Namespace Usage Information (2022-11-01 00:48:05 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Namespace| Node| Total|Expirations|Evictions| Stop|~~~~~~~~~~Device~~~~~~~~~~|~~~~~~~~~~Memory~~~~~~~~~|~Primary~
| |Records| | |Writes| Used|Used%|HWM%|Avail%| Used|Used%|HWM%|Stop%|~~Index~~
| | | | | | | | | | | | | | Type
test |172.17.0.2:3000|0.000 | 0.000 | 0.000 |False |0.000 B | 0.0| 0| 99|0.000 B | 0.0| 0| 90|shmem
test | |0.000 | 0.000 | 0.000 | |0.000 B | 0.0| | |0.000 B | 0.0| | |
Number of rows: 1
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Namespace Object Information (2022-11-01 00:48:05 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Namespace| Node|Rack| Repl| Total|~~~~~~~~~~Objects~~~~~~~~~~|~~~~~~~~~Tombstones~~~~~~~~|~~~~Pending~~~~
| | ID|Factor|Records| Master| Prole|Non-Replica| Master| Prole|Non-Replica|~~~~Migrates~~~
| | | | | | | | | | | Tx| Rx
test |172.17.0.2:3000| 0| 1|0.000 |0.000 |0.000 | 0.000 |0.000 |0.000 | 0.000 |0.000 |0.000
test | | | |0.000 |0.000 |0.000 | 0.000 |0.000 |0.000 | 0.000 |0.000 |0.000
Number of rows: 1The Aerospike Docker image comes with a default configuration file, which sets up a single node, single namespace developer environment. Alternatively, you can provide your own configuration file (see below).
You can inject parameters into the default configuration template using container-side environment variables with the -e flag.
For example, to set the default namespace name to demo:
docker run -d --name aerospike -e "NAMESPACE=demo" -p 3000-3002:3000-3002 -v /my/dir:/opt/aerospike/etc/ -e "FEATURE_KEY_FILE=/opt/aerospike/etc/features.conf" container.aerospike.com/aerospike/aerospike-server-enterpriseInjecting configuration parameters into the configuration template isn't compatible with providing a configuration file. You can use one or the other.
The feature_key_file of the service context which is only applicable and to Enterprise editions and must be set to the empty string when running the Community edition. Default: /etc/aerospike/features.conf.
The file param of the logging context. Default: "", do not log to file. The container will also log to `stdout`` regardless of what is configured here.
The bind address of the networking.service subcontext. Default: any
The port of the networking.service subcontext. Default: 3000
The single preconfigured namespace has the following variables:
The name of the namespace. Default: test
The storage-engine data-in-memory setting. If false (default), the namespace only stores the index in memory, and all reads and writes are served from the filesystem. If true the namespace storage is in-memory with filesystem persistence, meaning that reads and writes happen from a full in-memory copy, and a synchronous write persists to disk.
The namespace default-ttl. Default: 0
The namespace memory-size. Default: 1, the unit is always G (GB)
The namespace nsup-period. Default: 120 , nsup-period in seconds - also disabled when default-ttl is 0.
The namespace persistence file size. Default: 4, the unit is always G (GB)
You can override the default configuration file by providing your own aerospike.conf, as described in Configuring Aerospike Database.
You should first -v map a local directory, which Docker will bind mount. Next, drop your aerospike.conf file into this directory. Finally, use the --config-file option to tell Aerospike where in the container the configuration file is (the default path is /etc/aerospike/aerospike.conf). Remember that the feature key file is required, so use feature-key-file in your config file to point to a mounted path (such as /opt/aerospike/etc/feature.conf).
For example:
docker run -d -v /opt/aerospike/etc/:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-enterprise --config-file /opt/aerospike/etc/aerospike.confWith Docker, the files within the container are not persisted past the life of the container. To persist data, you will want to mount a directory from the host to the container's /opt/aerospike/data using the -v option:
For example:
docker run -d -v /opt/aerospike/data:/opt/aerospike/data -v /opt/aerospike/etc:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 -e "FEATURE_KEY_FILE=/opt/aerospike/etc/features.conf" container.aerospike.com/aerospike/aerospike-server-enterpriseThe example above uses the configuration template, where the single defined namespace is in-memory with file-based persistence. Just mounting the predefined /opt/aerospike/data directory enables the data to be persisted on the host.
Alternatively, your custom configuration file is used with the parameter file set to be a file in the mounted /opt/aerospike/data, such as in the following config snippet:
namespace test {
# :
storage-engine device {
file /opt/aerospike/data/test.dat
filesize 4G
data-in-memory true
}
}
In this example we also mount the data directory in a similar way, using a custom configuration file
docker run -d -v /opt/aerospike/data:/opt/aerospike/data -v /opt/aerospike/etc/:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-enterprise --config-file /opt/aerospike/etc/aerospike.confDocker provides an ability to expose a host's block devices to a running container. The --device option can be used to map a host block device within a container.
Update the storage-engine device section of the namespace in the custom Aerospike configuration file.
namespace test {
# :
storage-engine device {
device /dev/xvdc
write-block-size 128k
}
}
Now to map a host drive /dev/sdc to /dev/xvdc on a container
docker run -d --device '/dev/sdc:/dev/xvdc' -v /opt/aerospike/etc/:/opt/aerospike/etc/ --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-enterprise --config-file /opt/aerospike/etc/aerospike.confUpon restart, your Lua cache will become emptied. To persist the cache, you will want to mount a directory from the host to the container's /opt/aerospike/usr/udf/lua using the -v option:
docker run -d -v /opt/aerospike/lua:/opt/aerospike/usr/udf/lua -v /opt/aerospike/data:/opt/aerospike/data --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server-enterprise --config-file /opt/aerospike/etc/aerospike.confFor convenience, this image does not have security turned on by default, but it is a core Aerospike Enterprise Edition feature. The knowledge base article How To secure Aerospike database servers covers the topic well.
And Now for a Security Reminder that bad things can happen to good people.
Also see the knowledge base article How To secure Aerospike database servers.
Developers using the Aerospike Enterprise Edition single-node evaluation, and most others using Docker Desktop on their machine for development, will not need to configure the node for clustering. If you're interested in using clustering and have a feature key file without a single node limit or you are using the Community Edition, read the following sections.
In order for the Aerospike node to properly broadcast its address to the cluster and applications, the access-address configuration parameter needs to be set in the configuration file. If it is not set, then the IP address within the container will be used, which is not accessible to other nodes.
network {
service {
address any # Listening IP Address
port 3000 # Listening Port
access-address 192.168.1.100 # IP Address used by cluster nodes and applications
}
...
}
See How do I get a 2 nodes Aerospike cluster running quickly in Docker without editing a single file?
Aerospike Telemetry is a feature that allows us to collect certain anonymized usage data – not the database data – on your Aerospike Community Edition server use. More Info
[!TIP] Telemetry can be disabled by passing the environment variable
AEROSPIKE_TELEMETRYtoFALSEwithin the container's environment.
These images are based on Ubuntu or Red Hat UBI depending on the variant:
| Distro | Base Image |
|---|---|
| ubuntu22.04 | ubuntu:22.04 |
| ubuntu24.04 | ubuntu:24.04 |
| ubi9 | registry.access.redhat.com/ubi9/ubi-minimal:9.7 |
| ubi10 | registry.access.redhat.com/ubi10/ubi-minimal:10.0 |
| Lineage | Distros | Editions |
|---|---|---|
| 7.1 | ubuntu22.04, ubi9 | community, enterprise, federal |
| 7.2 | ubuntu24.04, ubi9 | community, enterprise, federal |
| 8.0 | ubuntu24.04, ubi9 | community, enterprise, federal |
| 8.1+ | ubuntu24.04, ubi10 | community, enterprise, federal |
Set up Docker Buildx for multi-architecture builds:
# Check if builder supports ARM
docker buildx inspect | grep -q "linux/arm" && echo "OK" || echo "Setup needed"
# If needed, create a multi-arch builder
docker run --privileged --rm tonistiigi/binfmt --install all
docker buildx create --name mybuilder --driver docker-container --bootstrap --useThe build system uses a modular design:
docker-build.sh Main entry point (usage, arg parsing, mode selection)
lib/
emit.sh Generate Dockerfiles (COPY install.sh approach)
update.sh In-place update of existing Dockerfiles (sed patching)
generate.sh Orchestration loop (routes between update and generate)
bake.sh Generate bake-multi.hcl for Docker buildx
support.sh Release/distro/edition support matrix
version.sh Version lookup, package URL generation
fetch.sh HTTP fetch helper
log.sh Colored logging functions
scripts/
deb/install.sh Single source of truth for DEB-based installs
rpm/install.sh Single source of truth for RPM-based installs
shasum-artifacts.sh Create .sha256 for local package dirs
Dockerfiles are persistent (checked into the repo) and compact. All installation logic lives in scripts/deb/install.sh and scripts/rpm/install.sh, which are COPY'd into the image and RUN during Docker build. This eliminates duplicated inline shell in Dockerfiles and makes the install logic independently testable.
| Mode | Command | Behavior |
|---|---|---|
| Update (default) | ./docker-build.sh -t 8.1 |
Patches existing Dockerfiles in-place (ARG values, SHAs, links). Refreshes support files (entrypoint.sh, install.sh, config). Auto-falls back to full generation if Dockerfile is missing. |
| Generate | ./docker-build.sh -g 8.1 |
Full regeneration from scratch. Removes releases/<lineage>/ for targeted lineages and writes fresh Dockerfiles. Use after structural changes (new distro, install script rewrite, etc.). |
| Generate + Build | ./docker-build.sh -g -t 8.1 |
Full regeneration, then builds locally. Combinable with -p for push. |
# First time: generate all Dockerfiles from scratch
./docker-build.sh -g 8.1
# Daily usage: update and build (patches SHAs/links in existing Dockerfiles)
./docker-build.sh -t 8.1
# Build specific edition and distro
./docker-build.sh -t 8.1 -e enterprise -d ubuntu24.04
# Build only Ubuntu distros (exclude UBI)
./docker-build.sh -t 8.1 -e enterprise -d ubuntu
# Build for specific architecture only
./docker-build.sh -t 8.1 -a amd64
# Build and push to registry (multi-arch)
./docker-build.sh -p 8.1 -e enterprise
# Build and push to a specific container registry (e.g. Artifactory)
./docker-build.sh -p 8.1 -e enterprise -r artifact.aerospike.io/database-docker-dev-local
# Build from local packages (no download)
./docker-build.sh -t 8.1.1.0 -e enterprise -u ./artifactsUsage: ./docker-build.sh -t|-p|-g [OPTIONS] [version|lineage]
MODE (one required):
-t Test mode - build and load locally
-p Push mode - build and push to registry (multi-arch)
-g, --generate Full Dockerfile regeneration (combinable with -t/-p)
OPTIONS:
-r, --registry REG Container registry for push mode.
Multiple: repeat -r (e.g. -r reg1 -r reg2). Default: aerospike.
-u, --url URL Custom artifacts URL or local directory path
-e, --edition ED Filter editions: community, enterprise, federal (multiple allowed)
-d, --distro DIST Filter distros: ubuntu22.04, ubuntu24.04, ubi9, ubi10
Prefix match: -d ubuntu (all Ubuntu), -d ubi (all UBI)
-a, --arch ARCH Filter architectures: amd64, arm64 (or x86_64, aarch64)
-T, --timestamp TS Fixed timestamp for push tags (YYYYMMDDHHMMSS)
--no-cache Disable Docker build cache
-h, --help Show full help
VERSION FORMATS:
8.1 Lineage (auto-detects latest version)
8.1.1.0 Specific release
8.1.1.0-rc2 Release candidate
8.1.1.0-start-16 Development build
# Test images built from releases/ directory
./test.sh 8.1 -e enterprise -d ubuntu24.04
# Test a specific image
./test.sh -i aerospike/aerospike-server-enterprise:8.1.1.0
# Test with specific platform
./test.sh -i aerospike/aerospike-server:8.1.1.0 -p linux/arm64# 1. Checkout and update
git checkout master && git pull
# 2. Generate fresh Dockerfiles and build test images
./docker-build.sh -g -t 8.1.1.0
# 3. Run tests
./test.sh 8.1
# 4. Build and push to registry
./docker-build.sh -p 8.1.1.0
# 5. Commit and tag
git add releases/ && git commit -m "8.1.1.0" && git tag -a "8.1.1.0" -m "8.1.1.0"
git push origin master --tags# Update existing Dockerfiles with new version SHAs/links and build
./docker-build.sh -t 8.1
# Or just update Dockerfiles without building
# (manually verify releases/ diffs, then commit)
./docker-build.sh -g 8.1
git diff releases/Docker images and Aerospike Database software are provided for use in accordance with the applicable license terms below. Aerospike, Inc. does not guarantee suitability for any particular purpose. Use of evaluation or commercial feature keys is subject to the agreements under which they were provided.
Aerospike Enterprise evaluation users, if you have any problems with or questions about this image, please post on the Aerospike discussion forum or open an issue in aerospike/aerospike-server.docker.
Enterprise customers are welcome to participate in the community forum, but can also report issues through the enterprise support system.
Community Edition users may report problems or ask questions about this image on the Aerospike Forums or open an issue in aerospike/aerospike-server.docker.
This repository (build scripts, templates, and tooling) is licensed under the Apache License, Version 2.0.
Aerospike Database in the Docker images is licensed as follows:
- If you are using the Aerospike Database Enterprise Edition evaluation feature key file, you are operating under the Aerospike Evaluation License Agreement.
- If you are using a feature key file you received as part of your commercial enterprise license, you are operating under the Aerospike Master License Agreement.
- If you are using Aerospike Database Community Edition, refer to the license information in the aerospike/aerospike-server repository.
Product license texts are also provided in the licenses/ directory (Community, Enterprise, Federal).