aerospike/aerospike-server repository overview

⁠Aerospike Community Edition Docker Image

⁠What is Aerospike?

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

Aerospike Community Edition supports the same developer APIs as Aerospike Enterprise Edition (except durable deletes), and differs in ease of operation and enterprise features. See the product matrix⁠ for more.

Anyone can sign up⁠ to get an evaluation feature key file for a full-featured, single-node Aerospike Enterprise Edition.

⁠Pull the Aerospike Docker image

docker pull aerospike/aerospike-server:latest 

⁠Running an Aerospike node

By using Aerospike Community Edition you agree to the COMMUNITY_LICENSE⁠.

docker run -d --name aerospike -p 3000-3002:3000-3002 container.aerospike.com/aerospike/aerospike-server

⁠Connecting to your Aerospike Container

You can use the latest aerospike-tools image to connect to your Aerospike container.

⁠Using aql

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)

OK

⁠Using asadm

docker 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|C-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|memory    
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: 1

⁠Customizing the Default Developer Environment

The 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/ container.aerospike.com/aerospike/aerospike-server

Injecting configuration parameters into the configuration template isn't compatible with providing a configuration file. You can use one or the other.

⁠List of template variables

⁠LOGFILE

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.

⁠SERVICE_ADDRESS

The bind address⁠ of the networking.service subcontext. Default: any

⁠SERVICE_PORT

The port⁠ of the networking.service subcontext. Default: 3000

⁠Preconfigured namespace

The single preconfigured namespace has the following variables:

⁠NAMESPACE

The name of the namespace. Default: test

⁠DATA_IN_MEMORY

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.

⁠DEFAULT_TTL

The namespace default-ttl⁠. Default: 0

⁠MEM_GB

The namespace memory-size⁠. Default: 1, the unit is always G (GB)

⁠NSUP_PERIOD

The namespace nsup-period⁠. Default: 120 , nsup-period in seconds - also disabled when default-ttl is 0.

⁠STORAGE_GB

The namespace persistence file size. Default: 4, the unit is always G (GB)

⁠Advanced Configuration

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 --config-file /opt/aerospike/etc/aerospike.conf

⁠Persistent data directory

With 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 container.aerospike.com/aerospike/aerospike-server

The 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 --config-file /opt/aerospike/etc/aerospike.conf

⁠Block storage

Docker 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 --config-file /opt/aerospike/etc/aerospike.conf

⁠Persistent Lua cache

Upon 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 --config-file /opt/aerospike/etc/aerospike.conf

⁠A note about security

For 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.

⁠Networking

⁠Configuring the node's access address

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
        }
    ...
    }

⁠Mesh clustering

See How do I get a 2 nodes Aerospike cluster running quickly in Docker without editing a single file?⁠

⁠Sending telemetry data to Aerospike

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⁠

⁠Image Versions

These images are based on ubuntu:*⁠.

⁠Reporting Issues

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⁠.

⁠License

If you are using Aerospike Database CE refer to the license information in the aerospike/aerospike-server⁠ repository.