Deployment

Provision the environment and execute the containerized stack to initialize the SandsBytes platform.

These instructions cover deploying and running the platform. Work through each section in order.

Prerequisites

Docker: Docker Engine and Docker Compose on the host. Install them before setup, or install them when prompted during setup (see Deploy (setup)).

Product package files:

package.tar.gz — SandsBytes files and Docker images.
product_key.tar.gz — Customer product key and licenses, and the nginx unique certificate.

System requirements

Hardware — Matching these targets supports concurrent parsing and search workloads.

Resource	Minimum	Recommended (Production)
CPU	6 Cores	12+ Cores
RAM	16 GB	64 GB+ (For high-speed hunting)
Storage	100 GB Free Space	SSD/NVMe (Scale based on data volume)

Note

Custom sizing: For enterprise environments with high-frequency ingestion, contact support@sandsbytes.com for hardware sizing.

Software and clients

Operating system: Linux Ubuntu 20.04.6 LTS or later (64-bit).
Browsers: Google Chrome, Mozilla Firefox, or Microsoft Edge (JavaScript enabled).
Connectivity: Internet access for initial dependency installation; optional afterward for external feeds and enrichment.

Stack components

The deployment runs these core services (use external instances only if your architecture exposes them separately).

Component	Role
UI (Vue.js)	Web interface for the application.
API (FastAPI)	Backend REST API and business logic.
Proxy (Nginx)	Reverse proxy and UI/API gateway.
Redis	Caching and Celery message brokering.
Celery	Asynchronous task queue and background workers.
Elasticsearch	Indexed record storage and Hunt telemetry.
SQL Database (MariaDB)	Primary application and cases metadata.

Configure environment variables

Prepare the folder

Create a folder and place package.tar.gz and product_key.tar.gz in it.

Extract both archives

tar -xzf product_key.tar.gz
tar -xzf package.tar.gz

Edit .env.override

Open .env.override and set the variables below.

Confidential values

Keep secure values private. Do not commit them or share them outside your operations team.

Secure values — Set each to a strong, unique value:

MARIADB_ROOT_PASSWORD — Database root account password.
MARIADB_PASSWORD — Database admin account password.
AUTH_SECRET_KEY — Secret key for authentication.
INTERNAL_EXECUTOR_TOKEN — Token for internal communication between services.
SMTP_ENCRYPTION_KEY — Key used to encrypt SMTP credentials.

Host IP — Set to your server’s IP address (replace <host-ip> everywhere):

NGINX_API_HOST — "<host-ip>"
NGINX_UI_HOST — "<host-ip>"
VITE_APP_API_HOST — "https://<host-ip>"
VITE_APP_GATEWAY_HOST — "<host-ip>"

Elasticsearch heap — Size JVM memory for Elasticsearch. Use about 50% of host RAM, capped at 32 GB:

ES_JAVA_OPTS='-Xms<size>g -Xmx<size>g'

Example on a 32 GB host (50% = 16 GB, under the cap): -Xms16g -Xmx16g.

Example reference block:

# ============ DB
MARIADB_ROOT_PASSWORD="changeme"
MARIADB_PASSWORD="changeme"

# =============== API
AUTH_SECRET_KEY="changeme"
INTERNAL_EXECUTOR_TOKEN="changeme"
SMTP_ENCRYPTION_KEY="changeme"

# =============== Nginx
NGINX_API_HOST="<host-ip>"
NGINX_UI_HOST="<host-ip>"

# ================= UI
VITE_APP_API_HOST="https://<host-ip>"
VITE_APP_GATEWAY_HOST="<host-ip>"

# ================= ES
ES_JAVA_OPTS='-Xms16g -Xmx16g'

Deploy (setup)

The SandsBytes Command Line Interface (CLI) can be executed using the command ./run.sh, which includes all needed actions to manage the solution.

SandsBytes CLI: interactive menu with Setup selected

Start deployment

Run ./run.sh and select the Setup action.

SandsBytes CLI: Setup selected and prompt to install Docker and Docker Compose (y/N)

Decide whether to install Docker Compose on the server. If Docker is already installed, skip that step by pressing N. If Docker is not installed, answer y when prompted to install Docker and Docker Compose.

The process loads Docker images into Docker Engine. Wait until loading is completed before continuing.

Run the platform

Start services

./run.sh

Choose run.

Check status

./run.sh

Choose status. Every container should show Up.

Sign in

Open a browser to https://<host-ip>.

Field	Value
Username	`admin`
Password	`Password@123`

CAUTION

Change the default password as soon as you sign in. Use User Profile → Change Password.

Stop the platform

./run.sh

Choose stop.

Deploying a new release

Prerequisites

A deployment from a previous package.
Archives for the new release (package.tar.gz, product_key.tar.gz).

Steps

Stop everything: ./run.sh → stop → all services.
Back up the old package folder: mv <package> <package>-backup
Create a folder for the new release, copy in the new product_key.tar.gz and package.tar.gz, then extract:

tar -xzf product_key.tar.gz
tar -xzf package.tar.gz

Load images: ./run.sh → setup.
Run the upgrade: ./run.sh → upgrade. When asked to restore data from the previous folder, answer Y, then enter the path to the backup folder (<package>-backup). The upgrade restores data and applies database schema updates if needed.

Troubleshooting

Logs for one service

./run.sh

Choose logs, then enter the service name when prompted.

Example service names (when your release exposes them): api, celery, proxy, ui, redis, db, es.

If problems persist, contact customer support.

Deployment

On this page