Community (Local) Edition
For prototyping or evaluation purposes, ApertureDB can be set up on-premises using our Docker-based community edition (terms of use).
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.
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 Setup
- Mac Setup
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
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.
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.
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:
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 Name | Description |
---|---|
ca | Generates SSL/TLS certificates using OpenSSL for secure communication between services. |
lenz | Runs the Lenz backend service, providing API endpoints and connecting to ApertureDB. |
aperturedb | The main ApertureDB database server, storing and managing your data. |
webui | The Web UI frontend, offering a lightweight web interface to interact with ApertureDB. |
nginx | Acts as a reverse proxy, routing HTTP/HTTPS traffic to the Web UI and API endpoints. |
-
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
orDB_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
Setup on Mac
Mac systems use ApertureDB's typical listening port (55555) for other purposes. Therefore, we need to tweak the Docker instructions to accommodate this variation.
You can do a quick install without ApertureDB UI, by executing this command:
docker run\
-p 55557:55555\
-e ADB_MASTER_KEY=admin\
-e ADB_FORCE_SSL=false\
aperturedata/aperturedb-community
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.
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.
To examine the contents of the database, you may want to map /aperturedb/db
and /aperturedb/logs
as volumes.
See docker compose examples below.
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 two 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:
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 Name | Description |
---|---|
ca | Generates SSL/TLS certificates using OpenSSL for secure communication between services. |
lenz | Runs the Lenz backend service, providing API endpoints and connecting to ApertureDB. The env variable ADB_PORT needs to be overriden to 55557 |
aperturedb | The main ApertureDB database server, storing and managing your data. |
webui | The Web UI frontend, offering a lightweight web interface to interact with ApertureDB. |
nginx | Acts as a reverse proxy, routing HTTP/HTTPS traffic to the Web UI and API endpoints. |
-
lenz also exposes port 55557 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
orDB_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=55557 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.