How to use Elasticsearch with Local Beach

This guide explains how to run a local Elasticsearch container for development of Neos and Flow projects.

 
 Local Beach

Overview

You can use the official Elasticsearch image for local development. Since Beach uses hosted Elasticsearch in production, this ensures the same behaviour across systems. The only difference is that the Local Beach version is without password protection.

If you have a running Local Beach setup for your project, adding Elasticsearch is just a matter of adding the container configuration.

Add Elasticsearch to Docker Compose

Open the .localbeach.docker-compose.yaml file of your Local Beach project and add the following at the end of the file:

  elasticsearch:
    image: elasticsearch:${BEACH_ELASTICSEARCH_IMAGE_VERSION}
    container_name: ${BEACH_PROJECT_NAME:?Please specify a Beach project name as BEACH_PROJECT_NAME}_elasticsearch
    networks:
      - local_beach
    ports:
      - 9200:9200
    volumes:
      - ./.LocalBeach/elasticsearch/data:/usr/share/elasticsearch/data
    ulimits:
      memlock:
        soft: -1
        hard: -1
    environment:
      - cluster.name=${BEACH_PROJECT_NAME:?Please specify a Beach project name as BEACH_PROJECT_NAME}
      - discovery.type=single-node
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"

If you don't need access to the Elasticsearch from the host, you can leave out the "ports" section. In case you need access, but want to run multiple Local Beach projects using Elasticsearch, adjust the port used on the host to avoid conflicts!

Make sure to edit the environment section below the php service in the same file, too:

  php:
    environment:
      - BEACH_ELASTICSEARCH_HOSTNAME=${BEACH_ELASTICSEARCH_HOSTNAME}
      - BEACH_ELASTICSEARCH_PORT=${BEACH_ELASTICSEARCH_PORT:-9200}
      - BEACH_ELASTICSEARCH_INDEX_NAME=${BEACH_ELASTICSEARCH_INDEX_NAME}

Now open the .localbeach.dist.env file and configure the Elasticsearch version to use:

BEACH_ELASTICSEARCH_IMAGE_VERSION=7.13.4

Configure Neos to use Elasticsearch

Next, you need to tell Neos where to find the Elasticsearch container. For example, if you are using Elasticsearch 7.x, the following configuration needs to go into your Configuration/Development/Beach/Instance/Settings.yaml:

Neos:
  ContentRepository:
    Search:
      elasticSearch:
        indexName: '%env:BEACH_ELASTICSEARCH_INDEX_NAME%'

Flowpack:
  ElasticSearch:
    clients:
      default:
        - host: '%env:BEACH_ELASTICSEARCH_HOSTNAME%'
          port: '%env:BEACH_ELASTICSEARCH_PORT%'

Flowpack:
  ElasticSearch:
    ContentRepositoryAdaptor:
      driver:
        version: 7.x

Edit .localbeach.dist.env to define the index name to use:

BEACH_ELASTICSEARCH_INDEX_NAME=someindexname

You should now be able to use Elasticsearch in you Local Beach setup.

If something is going wrong, you may first want to check the settings (for example by running ./flow configuration:show --type Settings in your Local Beach shell) and then look for any errors in the container logs (using beach local:logs).