Docker Images Guide

Container images: HeliosDB Full images are not published on Docker Hub or any other public registry. Images and Helm charts are provided through private registry access during onboarding: contact sales@heliosdb.com. The examples on this page use heliosdb-full:<tag>, an image built locally from the licensed source distribution (docker build -t heliosdb-full:<tag> .); replace it with the image reference you receive if you use the private registry.

This guide explains how to build and run the HeliosDB Full container image.

Where the image comes from

HeliosDB Full images are either provided through private registry access during onboarding, or built from the Dockerfile at the root of the licensed source distribution:

# From the root of the licensed source distribution
docker build -t heliosdb-full:<tag> .

The build compiles the heliosdb-full server in a Rust builder stage and copies it into a Debian slim runtime image. The image:

• runs heliosdb-full as its entrypoint, so arguments after the image name are passed to the server (for example --enable-mysql);
• runs as a non-root user;
• stores data in /var/lib/heliosdb/data (HELIOSDB_STORAGE_DATA_DIR);
• binds all interfaces inside the container (HELIOSDB_BIND_ADDR=0.0.0.0).

The source distribution contains further Dockerfiles for development and CI; the root Dockerfile is the one that produces the server image described here.

Running the image

Because the image binds all interfaces inside the container, the server refuses to start unless you opt in with HELIOSDB_ALLOW_EXTERNAL=1:

docker run -d --name heliosdb \
  -e HELIOSDB_ALLOW_EXTERNAL=1 \
  -p 127.0.0.1:5432:5432 \
  -p 127.0.0.1:8443:8443 \
  -v heliosdb-data:/var/lib/heliosdb/data \
  heliosdb-full:<tag>

Add listeners with flags after the image name, and publish their ports:

docker run -d --name heliosdb \
  -e HELIOSDB_ALLOW_EXTERNAL=1 \
  -p 127.0.0.1:5432:5432 -p 127.0.0.1:8443:8443 \
  -p 127.0.0.1:3306:3306 -p 127.0.0.1:1521:1521 \
  -v heliosdb-data:/var/lib/heliosdb/data \
  heliosdb-full:<tag> --enable-mysql --enable-oracle

For credentials and client examples, see the Quick Start.

Ports

Port	Listener	Enabled by
5432	PostgreSQL	default (--no-postgres turns it off)
8443	HTTP gateway (plain HTTP)	default (--no-http turns it off)
3306	MySQL	--enable-mysql
1521	Oracle (TNS)	--enable-oracle
1433	SQL Server (TDS)	--enable-sqlserver
27017	MongoDB	--enable-mongodb
9042	Cassandra (CQL)	--enable-cassandra
6379	Redis	--enable-redis

The image’s EXPOSE list names 8080 and 8081, which do not match the server’s default HTTP port; publish 8443 for the HTTP gateway (or set --http-port). MongoDB, Cassandra and SQL Server clients can connect and authenticate, and reading and writing HeliosDB tables through them is planned. The Redis listener keeps an in-memory keyspace that is not persisted. See the protocol hub for each listener.

Environment variables

Variable	Purpose
HELIOSDB_ALLOW_EXTERNAL	Required with the image’s 0.0.0.0 bind
HELIOSDB_STORAGE_DATA_DIR	Data directory (image default /var/lib/heliosdb/data)
HELIOSDB_POSTGRES_PORT, HELIOSDB_HTTP_PORT, HELIOSDB_MYSQL_PORT, HELIOSDB_MONGODB_PORT, …	Listener ports
HELIOSDB_API_KEY	API key for the HTTP gateway

The server logs at info level to standard output (docker logs heliosdb); add --verbose (-v) after the image name for debug output. All flags and variables are in the Server Configuration Reference.

Image Tagging Strategy

Tag images with the release version, and move a floating tag only after testing:

docker build -t heliosdb-full:<tag> .
docker tag heliosdb-full:<tag> heliosdb-full:latest

Registry Publishing

HeliosDB Full images are not published on Docker Hub or any other public registry; push the images you build to your own private registry.

Private Registry

docker tag heliosdb-full:<tag> registry.example.com/heliosdb-full:<tag>
docker push registry.example.com/heliosdb-full:<tag>

Security Scanning

Scan images for vulnerabilities:

# Using Docker Scout
docker scout cves heliosdb-full:<tag>

# Using Trivy
trivy image heliosdb-full:<tag>

# Using Snyk
snyk container test heliosdb-full:<tag>

Troubleshooting

Build Failures

Issue: Out of memory during build. The Rust build of heliosdb-full needs several GB of memory; raise the memory available to Docker (Docker Desktop settings, or the BuildKit builder’s limits) and retry.

Issue: Network timeouts while fetching dependencies

docker build --network host -t heliosdb-full:<tag> .

Runtime Issues

Issue: Container exits immediately

docker logs heliosdb
# "Refusing to bind '0.0.0.0' (non-loopback) without explicit opt-in":
# add -e HELIOSDB_ALLOW_EXTERNAL=1 to docker run

Issue: Permission denied on the data volume. The server runs as a non-root user; make sure a bind-mounted data directory is writable by that user, or use a named volume as in the examples above.

Best Practices

1. Always use multi-stage builds for smaller images
2. Pin base image versions to ensure reproducibility
3. Scan images regularly for security vulnerabilities
4. Use a .dockerignore to exclude unnecessary files
5. Set resource limits in production
6. Use health checks for container orchestration
7. Run as non-root user for security
8. Keep images minimal by removing build tools

Example .dockerignore

target/
.git/
.github/
docs/
tests/
benches/
*.md
Dockerfile*
docker-compose*

---

Next: Docker Compose Guide