# Sandbox VM Deployment The sandbox VM is an all-in-one Rierino environment that runs on a single machine using Docker Compose. It is designed for evaluation, training, and development workflows where you want everything bundled and runnable without Kubernetes. ### When to choose the sandbox VM Use this option when you want: * A single-VM environment with platform components and enabling systems included. * A quick way to explore the UI and core flows without provisioning a cluster. * A lightweight dev/test environment for one person or a small team. Choose Kubernetes instead when you need higher scale, high availability, or multi-node operations. ### Minimum VM requirements This environment requires a single VM with at least: * 4 vCPU * 16 GB RAM {% hint style="info" %} If you plan to enable more optional modules, allocate more RAM and disk. Start small, then scale up based on container memory usage. {% endhint %} ### What gets deployed The sandbox includes the following components. You can disable parts using Docker Compose profiles/services (see the sandbox repo README for the exact profile names and commands). * Admin UI * Admin Controller * Admin Runner (with Core platform services as well as optional PIM, CMS, training modules) * MongoDB Optional: * Ops Runner (used with optional modules for CDC and real-time data synch) * Kafka (and Kafka UI) * Elasticsearch * Redis * Browserless (for web scrapping use cases) * LocalAI (for local LLM models) * Prometheus (for metrics collection) * Quickwit (for logs collection) ### Get the sandbox assets The sandbox artifacts live in the public sandbox repository (requires credentials provided with the Rierino license): * The main runbook is in `composite/README.MD`. ### Prerequisites on the VM Before launching, make sure the VM has: * Docker Engine * Docker Compose (v2 recommended) * Network access to pull images and fetch artifacts from GitHub (or your internal mirrors) {% hint style="warning" %} If your VM sits behind strict egress controls, make sure it can reach your artifact sources (Docker registry + GitHub). Most “it won’t start” issues are just blocked outbound traffic. {% endhint %} ### Configuration #### Core settings (`composite/.env`) Set the following variables in `composite/.env` before you start: * RIERINO\_VERSION: Rierino version to be deployed * GITHUB\_USER: Provided username for access to Rierino assets * GITHUB\_AUTH\_TOKEN: Provided authentication token for access to Rierino assets #### Optional: AI enablement For using GenAI models on runners, LLM provider related secret configuration can be added to globalsecrets.properties file under admin\_runner folder before restarting services. Training examples use OpenAI as the sample provider, which can be configured by setting the following key/value in this file. ```java-properties rierino.system.openai.apikey=YOUR_API_KEY ``` For using embedded RAI frontend agents, OpenAI related environment variables can be configured in "composite/adminui.env" file, enabling AI assistant use in admin UI. **Using Local LLM Models** If you prefer to use local LLM models instead of an external provider, it is possible with the following steps: * Deploy localai service using `docker compose up localai` command * LocalAI will be available on `http://[YOUR_VM_IP]:3333` address with "local" as the login token * Activate the model(s) and backend(s) you would like to use, or upload your custom trained model * You can then use this model in GenAI model screen either with LocalAI settings or OpenAI (setting baseUrl to `http://localai.admin-backend.svc.cluster.local:8080`) since LocalAI service supports standard OpenAI APIs as well #### Optional: Monitoring enablement By default all logs are printed on the docker container console, however all Rierino backend services support OpenTelemetry feeds for metrics, traces and logs, which can be used with optional components for more structured monitoring even in the sandbox deployment. * Deploy prometheus and quickwit services using `docker compose` command * Edit .env file with the following parameter values for exporting logs and metrics and run docker compose up for runner services to apply changes: {% code overflow="wrap" %} ```dotenv JAVA_TOOL_OPTIONS="-javaagent:/app/data/opentelemetry-javaagent.jar -Dotel.instrumentation.logback-appender.enabled=true -Dotel.instrumentation.logback-appender.experimental.capture-mdc-attributes=* -Dotel.instrumentation.common.default-enabled=false -Dotel.instrumentation.opentelemetry-api.enabled=true" OTEL_INSTRUMENTATION_ENABLED=true OTEL_METRICS_EXPORTER=otlp OTEL_LOGS_EXPORTER=otlp OTEL_EXPORTER_OTLP_COMPRESSION=gzip OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION=BASE2_EXPONENTIAL_BUCKET_HISTOGRAM OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://quickwit.admin-backend.svc.cluster.local:7281 OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://prometheus.admin-backend.svc.cluster.local:9090/api/v1/otlp/v1/metrics OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf ``` {% endcode %} **Monitoring in Admin UI** Saga screens include a monitoring tab, displaying metrics and logs specific to the current saga and its steps. These information are already mapped in the Saga UI design screen, all you need to do for activating display of this data is uncommenting the lines in Handlebars displays configured in this screen.
What goes where (quick map) * `composite/.env` controls the overall sandbox deployment (version, access credentials, public address). * `composite/adminui.env` controls UI-side AI agent integration. * `admin_runner/globalsecrets.properties` controls runner-side secrets (including GenAI keys).
### Launch Once the environment files are set, `compose/compose.yaml` can be used to launch the services. {% stepper %} {% step %} ### Configure environment files Update: * `composite/.env` * `composite/adminui.env` (optional) * `admin_runner/globalsecrets.properties` (optional) {% endstep %} {% step %} ### Start the stack Run Docker Compose using `compose/compose.yaml`. Use profiles/services to enable or disable optional components. Example command pattern (adjust to match the repo README): ```sh docker compose -f compose/compose.yaml up -d ``` {% endstep %} {% step %} ### Validate that it’s healthy After containers start, validate: * Admin UI is reachable in a browser. * Admin backend services are up (check container logs if the UI cannot load). * MongoDB is running. If something fails fast, start with `docker compose logs -f` and check for missing env vars or blocked network access. {% endstep %} {% endstepper %} ### Basic operations (day 2) Common patterns (exact commands depend on the compose setup in the repo): * **Stop:** bring down the stack when you don’t need it. * **Upgrade:** bump `RIERINO_VERSION`, then restart the affected services. * **Toggle components:** use compose profiles/services to run a smaller footprint. {% hint style="warning" %} Treat this VM like a dev/test environment. Use separate credentials and non-production secrets where possible. {% endhint %} The sandbox assets can be found at the [sandbox repository](https://github.com/rierino-open/sandbox) with "composite/README.MD" file for more details on launch and administration commands. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.rierino.com/installation/deployment-alternatives/sandbox-vm-deployment.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.