--- title: "Docker Images Guide" --- # 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](mailto:sales@heliosdb.com). The examples on this page use `heliosdb-full:`, an image built locally from the licensed source distribution (`docker build -t heliosdb-full: .`); 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: ```bash # From the root of the licensed source distribution docker build -t heliosdb-full: . ``` 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`: ```bash 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: ``` Add listeners with flags after the image name, and publish their ports: ```bash 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: --enable-mysql --enable-oracle ``` For credentials and client examples, see the [Quick Start](/docs/full/quickstart/). ### 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](/docs/full/reference/protocols/) 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](/docs/full/reference/configuration/). ## Image Tagging Strategy Tag images with the release version, and move a floating tag only after testing: ```bash docker build -t heliosdb-full: . docker tag heliosdb-full: 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 ```bash docker tag heliosdb-full: registry.example.com/heliosdb-full: docker push registry.example.com/heliosdb-full: ``` ## Security Scanning Scan images for vulnerabilities: ```bash # Using Docker Scout docker scout cves heliosdb-full: # Using Trivy trivy image heliosdb-full: # Using Snyk snyk container test heliosdb-full: ``` ## 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 ```bash docker build --network host -t heliosdb-full: . ``` ### Runtime Issues **Issue:** Container exits immediately ```bash 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