Skip to content
Klutch.sh Docs

Deploying an OpenSearch App

Introduction

OpenSearch is an open-source search and analytics suite derived from Elasticsearch. Deploying OpenSearch with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage for indices—all configured from klutch.sh/app. This guide covers installation, repository prep, a production-ready Dockerfile, deployment steps, Nixpacks overrides, sample API usage, and production tips.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your OpenSearch Dockerfile (GitHub is the only supported git source)
  • Sizing for disk and memory based on your index needs
  • Optional: TLS certificates and security configuration

For onboarding, see the Quick Start.

Architecture and ports

  • REST API: internal port 9200 (HTTP).
  • Transport: internal port 9300 (TCP, for clustering).
  • Choose HTTP traffic and set the internal port to 9200 for REST; use TCP/9300 if you cluster across apps.
  • Persistent storage is required for data and logs.

Repository layout

opensearch/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets and credentials out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Validate locally before pushing to GitHub:

Terminal window
docker build -t opensearch-local .
docker run -p 9200:9200 -p 9300:9300 \
  -e "discovery.type=single-node" \
  opensearch-local

Dockerfile for OpenSearch (production-ready)

Place this Dockerfile at the repo root; Klutch.sh auto-detects it (no Docker selection in the UI):

FROM opensearchproject/opensearch:2.12.0


ENV discovery.type=single-node \
    plugins.security.disabled=true \
    bootstrap.memory_lock=true \
    OPENSEARCH_JAVA_OPTS="-Xms512m -Xmx512m"


EXPOSE 9200 9300
CMD ["./opensearch-docker-entrypoint.sh"]

Notes:

  • Pin the image tag (e.g., 2.12.x) for stability; update intentionally.
  • For production, enable security (remove plugins.security.disabled=true), configure TLS, and set proper discovery settings if clustering.

Environment variables (Klutch.sh)

Set these in Klutch.sh before deploying:

  • discovery.type=single-node (or zen2 settings for clusters)
  • plugins.security.disabled=true (set to false in production and configure TLS/users)
  • OPENSEARCH_JAVA_OPTS=-Xms1g -Xmx1g (adjust to memory limits)
  • Optional: bootstrap.memory_lock=true, DISABLE_INSTALL_DEMO_CONFIG=true when enabling security

If you deploy without the Dockerfile and need Nixpacks overrides:

  • NIXPACKS_START_CMD=./opensearch-docker-entrypoint.sh

Attach persistent volumes

In Klutch.sh storage settings, add mount paths and sizes (no names required):

  • /usr/share/opensearch/data — index data.
  • /usr/share/opensearch/logs — logs (optional).

Ensure these directories are writable inside the container.

Deploy OpenSearch on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 9200. If clustering, set up a TCP app for 9300 as well.
  4. Add the environment variables above, tuning memory and security for your workload.
  5. Attach persistent volumes for /usr/share/opensearch/data (and /usr/share/opensearch/logs if needed), sized for your index and log retention.
  6. Deploy. Your OpenSearch endpoint will be reachable at https://example-app.klutch.sh; connect clients to REST on 9200.

Sample API usage

Create an index and add a document:

Terminal window
curl -X PUT "https://example-app.klutch.sh/my-index" \
  -H "Content-Type: application/json" \
  -d '{ "settings": { "number_of_shards": 1, "number_of_replicas": 0 } }'


curl -X POST "https://example-app.klutch.sh/my-index/_doc/1" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Hello from OpenSearch on Klutch.sh" }'

Search:

Terminal window
curl -X GET "https://example-app.klutch.sh/my-index/_search?q=hello"

Health checks and production tips

  • Add an HTTP probe to /_cluster/health for readiness.
  • Enforce HTTPS at the edge; forward internally to port 9200.
  • Enable security for production, configure TLS, and manage users/roles.
  • Monitor JVM heap and disk usage; resize /usr/share/opensearch/data before it fills.
  • Pin image versions and test upgrades in staging; snapshot data before updates.

OpenSearch on Klutch.sh combines reproducible Docker builds with managed secrets, persistent storage, and flexible HTTP/TCP routing. With the Dockerfile at the repo root, port 9200 configured, and data persisted, you can deliver search and analytics without extra YAML or workflow overhead.