Skip to main content

Community (Local) Edition

For prototyping or evaluation purposes, ApertureDB can be set up on-premises using our Docker-based community edition (terms of use).

tip

ApertureDB can be and preferably should be installed as a distributed database for high availability and performance as described in the earlier setup methods.

We have packaged ApertureDB and all the dependencies in a set of docker images that can be pulled from our DockerHub or cloud-specific container registry.

info

We recommend using a machine with 8 cores, with 32 GB memory, and 200 GB storage for common use cases, e.g. EC2 VM of type m6i.4xlarge or GCP VM of e2-standard-8. However, the Docker itself foregoes some optimizations for vector search in order to support x86-64 and M1+ architectures.

Non-Mac Systems​

For testing ApertureDB on Linux systems, you can do a quick install without ApertureDB UI, by executing this command:

docker run\
  -p 55555:55555\
  -e ADB_MASTER_KEY=admin\
  -e ADB_FORCE_SSL=false\
  aperturedata/aperturedb-community
warning

Note that it's not straightforward to describe the setup with SSL as that needs additional services to be setup.

The ADB_FORCE_SSL parameter above disables SSL. Best practice would be to use SSL, but setting that up is somewhat complex and error-prone. See the docker compose solution below for an alternative approach.

info

The default login and password for Community edition is admin:admin, and for the other methods, is chosen by the user at setup time).

This command will pull the Docker image if not already present. To force an update to the latest, you can first run:

docker pull aperturedata/aperturedb-community

before executing the "run" command.

tip

To examine the contents of the database, you may want to map /aperturedb/db and /aperturedb/logs as volumes. See docker compose examples below.

Check out this setup video:

Run ApertureDB along with WebUI using Docker Compose​

ApertureDB has an associated Web UI that provides a lightweight web interface. Save the following as docker-compose.yml (or download here, make sure to match the name), and follow the instructions below to start the services together.

name: aperturedb-community-local

services:
  ca:
    image: nginx
    restart: on-failure
    command: |
      bash -c "
      openssl genpkey -algorithm RSA -out /ca/ca.key -aes256 -pass pass:1234
      openssl req -x509 -new -nodes -key /ca/ca.key -sha256 -days 3650 -out /ca/ca.crt -subj \"/C=US/ST=CA/L=Los Gatos/O=ApertureData/OU=ApertureDataCA/CN=ApertureDataCA\" -passin pass:1234
      openssl genrsa -out /cert/tls.key 4096
      openssl req -new -key /cert/tls.key -out /ca/tcp.csr -days 3650 -subj \"/C=US/ST=NY/L=NYC/O=instance/OU=instanceDB/CN=${DB_TCP_CN:-localhost}\"
      openssl x509 -req  -CA /ca/ca.crt -CAkey /ca/ca.key -in /ca/tcp.csr -out /cert/tcp.crt -passin pass:1234
      openssl req -new -key /cert/tls.key -out /ca/http.csr -days 3650 -subj \"/C=US/ST=NY/L=NYC/O=instance/OU=instanceDB/CN=${DB_HTTP_CN:-localhost}\"
      openssl x509 -req  -CA /ca/ca.crt -CAkey /ca/ca.key -in /ca/http.csr -out /cert/http.crt -passin pass:1234"
    volumes:
      - ./aperturedb/certificate:/cert
      - ./ca:/ca

  lenz:
    depends_on:
      ca:
        condition: service_completed_successfully
      aperturedb:
        condition: service_started
    image: aperturedata/lenz:latest
    ports:
      - ${ADB_PORT}:55551
    restart: always
    environment:
      LNZ_HEALTH_PORT: 58085
      LNZ_TCP_PORT: 55551
      LNZ_HTTP_PORT: 8080
      LNZ_ADB_BACKENDS: '["aperturedb:55553"]'
      LNZ_REPLICAS: 1
      LNZ_ADB_MAX_CONCURRENCY: 48
      LNZ_FORCE_SSL: false
      LNZ_CERTIFICATE_PATH: /etc/lenz/certificate/tcp.crt
      LNZ_PRIVATE_KEY_PATH: /etc/lenz/certificate/tls.key
    volumes:
      - ./aperturedb/certificate:/etc/lenz/certificate

  aperturedb:
    healthcheck:
      test:
        - CMD-SHELL
        - "bash -lc 'echo > /dev/tcp/127.0.0.1/55553'"
      interval: 2s
      timeout: 1s
      retries: 60
    image: aperturedata/aperturedb-community:latest
    volumes:
      - ./aperturedb/db:/aperturedb/db
      - ./aperturedb/logs:/aperturedb/logs
    restart: always
    environment:
      ADB_KVGD_DB_SIZE: "204800"
      ADB_LOG_PATH: "logs"
      ADB_ENABLE_DEBUG: 1
      ADB_MASTER_KEY: "admin"
      ADB_PORT: 55553
      ADB_FORCE_SSL: false

  webui:
    image: aperturedata/aperturedata-platform-web-private:latest
    restart: always

  nginx:
    depends_on:
      ca:
        condition: service_completed_successfully
    image: nginx
    restart: always
    ports:
      - 8087:80
      - 8443:443
    configs:
      - source: nginx.conf
        target: /etc/nginx/conf.d/default.conf
    volumes:
      - ./aperturedb/certificate:/etc/nginx/certificate

configs:
  nginx.conf:
    content: |
      server {
        listen 80;
        listen 443 ssl;
        client_max_body_size 256m;
        ssl_certificate /etc/nginx/certificate/http.crt;
        ssl_certificate_key /etc/nginx/certificate/tls.key;
        location / {
          proxy_pass http://webui;
        }
        location /api/ {
          proxy_pass http://lenz:8080;
        }
      }

Here is a summary of the services that have been described:

Service NameDescription
caGenerates SSL/TLS certificates using OpenSSL for secure communication between services.
lenzRuns the Lenz backend service, providing API endpoints and connecting to ApertureDB.
aperturedbThe main ApertureDB database server, storing and managing your data.
webuiThe Web UI frontend, offering a lightweight web interface to interact with ApertureDB.
nginxActs as a reverse proxy, routing HTTP/HTTPS traffic to the Web UI and API endpoints.
info

  • lenz also exposes port 55555 to the docker host.

  • nginx also exposes ports 8087, 8443 to the docker host.

  • The ca service generates certificates into ./aperturedb/certificate and ./ca folders . Please make a note of the absolute path to ca.crt.

  • If your virtual env is going to be on another machine, this ca.crt needs to be copied there, and it's absolute path in the destination machine needs to be noted. Also in such a case the environment variable DB_TCP_CN or DB_HTTP_CN needs to be set to be the hostname of the machine running aperturedb.

The following commands can bring up the setup as described.

ADB_PORT=55555 DB_TCP_CN=localhost DB_HTTP_CN=localhost docker compose up --detach

This will launch the docker containers in the background. You can remove --detach to launch them in the foreground.

To make sure you get the latest versions of the docker images:

docker compose pull

docker compose up --detach

To stop the database server, simply run:

docker compose down

Start Building With ApertureDB​

Learn how to connect to the server with the various ApertureDB client alternatives.

You can join our slack channel to connect with the community, ask any questions, and stay in touch with the ApertureData team.