Skip to main content

Aerospike

What is Aerospike?​

Aerospike is a distributed, high-performance NoSQL key-value database built for low-latency reads and writes at scale, commonly used for real-time use cases like ad targeting, fraud detection, and session stores.

Start Aerospike​

./laradock start aerospike

Your data is created on first start and kept between restarts.

Stop Aerospike​

Stopping just pauses the container; your data is safe:

./laradock stop aerospike

To delete the container entirely (the data on disk is still untouched, it lives under DATA_PATH_HOST):

./laradock remove aerospike

Configuration​

All settings live in aerospike/defaults.env and can be overridden by adding the same line to your own .env:

VariableDefaultWhat it does
AEROSPIKE_SERVICE_PORT3000Host-side port for the client service port.
AEROSPIKE_FABRIC_PORT3001Host-side port for inter-node cluster communication.
AEROSPIKE_HEARTBEAT_PORT3002Host-side port for cluster heartbeat messages.
AEROSPIKE_INFO_PORT3003Host-side port for the info/monitoring protocol.
AEROSPIKE_STORAGE_GB1Storage size (in GB) allocated to the container, passed in as STORAGE_GB.
AEROSPIKE_MEM_GB1Memory limit (in GB) for the container, passed in as MEM_GB.
AEROSPIKE_NAMESPACEtestDefault Aerospike namespace created on boot, passed in as NAMESPACE.

Change namespace, storage, or memory limits​

AEROSPIKE_NAMESPACE, AEROSPIKE_STORAGE_GB, and AEROSPIKE_MEM_GB are passed into the container as plain runtime environment variables (not baked in at build time), so a restart is enough to apply a change, no rebuild needed. Set the new value in .env, then:

./laradock restart aerospike

Changing AEROSPIKE_NAMESPACE doesn't rename or migrate data already stored under the old namespace, it just changes which namespace the server exposes on boot.

Change the Aerospike version​

The version is pinned by the AEROSPIKE_VERSION build arg at the top of aerospike/Dockerfile (ce-8.1.2.2 by default), it isn't exposed as an .env variable. Edit that line to the tag you want from Aerospike's Docker Hub, then rebuild:

./laradock rebuild aerospike

Connect from PHP​

Aerospike needs its own PHP extension to talk to the server from php-fpm/workspace. That's a separate install step, see Install the Aerospike extension for the WORKSPACE_INSTALL_AEROSPIKE/PHP_FPM_INSTALL_AEROSPIKE flags and rebuild command.

Once installed, connect to the server by container name and service port:

$client = new Aerospike(["hosts" => [["addr" => "aerospike", "port" => 3000]]]);

Connect from your host machine​

Inside Laradock, other containers reach it by container name: aerospike:3000. From your own machine, connect to localhost:3000 (or your custom AEROSPIKE_SERVICE_PORT) using the Aerospike CLI tools or a compatible client.

Check node status​

Open a terminal inside the container, then ask the running node for its status:

./laradock enter aerospike
asinfo -v status

A healthy node replies ok. Run asinfo -v namespaces the same way to list the namespaces currently configured on the node.

Backup and restore​

Aerospike's data lives entirely under the DATA_PATH_HOST/aerospike volume mount, so backing it up is a matter of stopping the node and copying that folder while nothing is writing to it.

Back up:

./laradock stop aerospike
cp -r "${DATA_PATH_HOST:-~/.laradock/data}/aerospike" ./aerospike-backup-$(date +%Y%m%d)
./laradock start aerospike

Restore from a backup folder made the same way (⚠️ this replaces everything currently in DATA_PATH_HOST/aerospike):

./laradock stop aerospike
rm -rf "${DATA_PATH_HOST:-~/.laradock/data}/aerospike"
cp -r ./aerospike-backup-20260101 "${DATA_PATH_HOST:-~/.laradock/data}/aerospike"
./laradock start aerospike

Start completely fresh (wipe all data)​

To throw away everything and start Aerospike from a clean, empty state (⚠️ this permanently deletes all data in this container, back up first if you need anything):

./laradock stop aerospike
./laradock remove aerospike
rm -rf "${DATA_PATH_HOST:-~/.laradock/data}/aerospike"
./laradock start aerospike

DATA_PATH_HOST is whatever you have set in .env (~/.laradock/data by default), so the folder above is where Aerospike's data actually lives on your machine.

Talk to this from another Laradock project​

Each Laradock project is its own isolated Docker network by default, so a second project's containers can't reach this Aerospike by container name out of the box. Easiest fix: the service, fabric, heartbeat, and info ports are already published to your host, so have the other project connect to your host machine's address instead of aerospike, for example host.docker.internal (Docker Desktop) with the port set to this project's AEROSPIKE_SERVICE_PORT. Make sure the two projects use different values for all four Aerospike ports if they're both running at once.

Common issues​

  • Client can't connect at all. Aerospike needs all four ports (service, fabric, heartbeat, info) reachable for the node to run correctly, not just the service port. Confirm none of AEROSPIKE_SERVICE_PORT/AEROSPIKE_FABRIC_PORT/AEROSPIKE_HEARTBEAT_PORT/AEROSPIKE_INFO_PORT collide with something else on your host.
  • "Namespace not found" errors. Your client is targeting a namespace that doesn't match AEROSPIKE_NAMESPACE (default test). Either use that namespace or change AEROSPIKE_NAMESPACE and ./laradock restart aerospike.
  • PHP calls fail with "class Aerospike not found." The PHP extension isn't installed yet, it's not bundled by default. Follow Install the Aerospike extension and rebuild workspace/php-fpm.
  • Out-of-memory or storage errors under real load. AEROSPIKE_MEM_GB/AEROSPIKE_STORAGE_GB default to 1, fine for local dev, but bump them in .env if you're testing with meaningful data volumes, then ./laradock restart aerospike.
  • Node reports itself unhealthy after a host reboot. Run ./laradock logs aerospike and check for storage errors before assuming data is lost, a node re-joining after an unclean shutdown can take a few seconds to come back to ok in asinfo -v status.

New to Laradock? Start at Getting Started.