OpenSearch Docker Compose - Multi-Node Cluster

A production-ready Docker Compose setup for running a multi-node OpenSearch cluster with SSL/TLS encryption, security plugins, and OpenSearch Dashboards.

Features

• Multi-node cluster: Two-node OpenSearch cluster for high availability
• SSL/TLS encryption: Automatic certificate generation for secure communication
• Security plugin: Full security enabled with certificate-based authentication
• OpenSearch Dashboards: Web UI for cluster management and visualization
• One-time setup: Certificate generation runs automatically on first start
• Best practices: Follows OpenSearch and Docker Compose best practices

Quick Start

1. Copy the environment file:

   cp example.env .env

2. Review and customize .env (especially passwords):

   # Edit .env to change default passwords and other settings
   nano .env

3. Start the cluster:

   docker-compose up -d

4. Verify the cluster is running:

   docker-compose ps

5. Access OpenSearch Dashboards:

   • URL: http://localhost:5601
   • Default username: admin
   • Default password: admin (or whatever you set in .env)

6. Access OpenSearch API:

   curl -k -u admin:admin https://localhost:9200

Architecture

Services

• opensearch-setup: Generates SSL certificates on first run, then exits
• opensearch-node1: First OpenSearch node (master-eligible)
• opensearch-node2: Second OpenSearch node (master-eligible)
• opensearch-dashboards: Web UI for OpenSearch

Network

All services run on a dedicated bridge network (opensearch-network) for isolation.

Volumes

• certs: Shared volume for SSL certificates (generated by opensearch-setup)
• opensearch-data1: Persistent data for node1
• opensearch-data2: Persistent data for node2

How opensearch-setup Works

The opensearch-setup container runs only once when you first start the cluster:

1. Checks if certificates already exist in the certs volume
2. If certificates exist, exits immediately (skips generation)
3. If certificates don't exist:
   • Generates a Root CA certificate
   • Generates certificates for admin, node1, node2, and dashboards
   • Sets proper file permissions
   • Exits successfully

The container uses a healthcheck that verifies certificate existence. Once healthy, dependent services (opensearch-node1, opensearch-node2, opensearch-dashboards) start automatically.

Note: After the first run, the opensearch-setup container will be in "exited" state, which is expected behavior.

Environment Variables

Required Variables

All variables have defaults, so the cluster will run with cp example.env .env without modification. However, you should change passwords before production use.

Key Variables

Variable	Default	Description
COMPOSE_PROJECT_NAME	opensearch-cluster	Docker Compose project name
OPENSEARCH_VERSION	latest	OpenSearch image tag
OPENSEARCH_DASHBOARDS_VERSION	latest	OpenSearch Dashboards image tag
OPENSEARCH_CLUSTER_NAME	opensearch-cluster	Cluster name (must match across nodes)
OPENSEARCH_INITIAL_ADMIN_PASSWORD	admin	CHANGE THIS - Initial admin password
OPENSEARCH_USERNAME	admin	Dashboards username
OPENSEARCH_PASSWORD	admin	CHANGE THIS - Dashboards password
OPENSEARCH_JAVA_OPTS	-Xms2g -Xmx2g	Java heap size (50% of memory limit)
OPENSEARCH_MEMORY_LIMIT	4G	Memory limit per node
OPENSEARCH_CPU_LIMIT	4.0	CPU limit per node
CERT_ORGANIZATION	OpenSearch	Certificate organization name
CERT_COUNTRY	US	Certificate country code
CERT_STATE	CA	Certificate state/province
CERT_LOCALITY	San Francisco	Certificate city/locality

See example.env for all available variables with descriptions.

Certificate Configuration

Certificate Distinguished Names (DNs)

The certificates generated by opensearch-setup use Distinguished Names (DNs) in the format:

CN=<common-name>,O=<organization>,L=<locality>,ST=<state>,C=<country>

Automatic DN Configuration

The opensearch-setup container automatically updates the DN values in the OpenSearch config files (opensearch-node1.yml and opensearch-node2.yml) to match the certificate subjects it generates. This ensures the DNs always stay in sync.

The DN values are configured in:

• plugins.security.authcz.admin_dn: Admin certificate DN
• plugins.security.nodes_dn: Node certificate DNs

Default DN values (matching default certificate variables):

• Organization: OpenSearch
• Country: US
• State: CA
• Locality: San Francisco

Customizing Certificate DNs

To customize certificate DNs, simply set the certificate environment variables in your .env file:

CERT_ORGANIZATION=MyCompany
CERT_COUNTRY=US
CERT_STATE=NY
CERT_LOCALITY=New York

The setup script will automatically:

1. Generate certificates with these values
2. Update the DN values in both opensearch-node1.yml and opensearch-node2.yml

Important: After changing certificate variables, you must:

1. Remove the certs volume: docker-compose down -v
2. Restart to regenerate certificates and update config files: docker-compose up -d

Security Best Practices

Before Production Use

1. Change all default passwords:

   • OPENSEARCH_INITIAL_ADMIN_PASSWORD
   • OPENSEARCH_PASSWORD

2. Use specific version tags instead of latest:

   • OPENSEARCH_VERSION=3.3.2
   • OPENSEARCH_DASHBOARDS_VERSION=3.3.0

3. Customize certificate organization:

   • Set CERT_ORGANIZATION to your organization name
   • Update DN values in config files accordingly

4. Review resource limits:

   • Adjust OPENSEARCH_MEMORY_LIMIT and OPENSEARCH_CPU_LIMIT based on your hardware
   • Ensure OPENSEARCH_JAVA_OPTS heap size is ~50% of memory limit

5. Network security:

   • Consider using Docker secrets for passwords in production
   • Restrict port exposure if not needed externally
   • Use firewall rules to limit access

6. Regular updates:

   • Keep OpenSearch and Dashboards versions up to date
   • Review security advisories regularly

Troubleshooting

Certificates Not Generated

If certificates fail to generate:

1. Check opensearch-setup logs: docker-compose logs opensearch-setup
2. Ensure the container has write permissions to the certs volume
3. Remove volumes and restart: docker-compose down -v && docker-compose up -d

Cluster Not Forming

If nodes don't join the cluster:

1. Check node logs: docker-compose logs opensearch-node1 opensearch-node2
2. Verify certificate DNs match between certificates and config files
3. Ensure both nodes can communicate on the network
4. Check discovery settings in node config files

Authentication Failures

If you can't authenticate:

1. Verify passwords match in .env and Dashboards config
2. Check that OPENSEARCH_INITIAL_ADMIN_PASSWORD matches what you're using
3. Review security plugin logs in node logs

Port Conflicts

If ports are already in use:

1. Change port mappings in .env:
   • OPENSEARCH_PORT_1 (default: 9200)
   • OPENSEARCH_DASHBOARDS_PORT (default: 5601)

Maintenance

Viewing Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f opensearch-node1

Stopping the Cluster

docker-compose down

Stopping and Removing Volumes

# WARNING: This deletes all data!
docker-compose down -v

Restarting After Changes

# Restart all services
docker-compose restart

# Recreate containers (useful after config changes)
docker-compose up -d --force-recreate

License

See LICENSE file for details.

Contributing

This is a best-practice example. Feel free to fork and adapt for your needs.