> For the complete documentation index, see [llms.txt](https://icij.gitbook.io/datashare/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://icij.gitbook.io/datashare/local-mode/about-the-local-mode/embedded-mode.md).

# Embedded mode

In embedded mode, Datashare bundles all the services it needs (database, search engine, message bus) directly inside the application. You don't need to install or configure these services separately — everything starts automatically when you launch Datashare.

## How it works

Under the hood, Datashare embeds the following services:

| Service       | Technology                       | Notes                                      |
| ------------- | -------------------------------- | ------------------------------------------ |
| Message bus   | [Qpid](https://qpid.apache.org/) | Runs inside Datashare                      |
| Task queues   | Java memory queues               | Runs inside Datashare                      |
| Database      | SQLite                           | Can be stored in memory or in a file       |
| Search engine | Elasticsearch                    | Runs as a **separate process** (see below) |

### About Elasticsearch

Since Elasticsearch 8, it can no longer run inside Datashare directly. Starting from **Datashare 21**, Elasticsearch is launched as a separate process alongside Datashare.

This means two Java processes run on your machine: one for Datashare, one for Elasticsearch. You may need to adjust how much memory each process is allowed to use, depending on the size of your documents and the resources available on your machine.

To do so, use the following environment variables:

| Variable       | Controls                          |
| -------------- | --------------------------------- |
| `DS_JAVA_OPTS` | Memory allocated to Datashare     |
| `ES_JAVA_OPTS` | Memory allocated to Elasticsearch |

For example, to give 2 GB to Elasticsearch and 1 GB to Datashare:

```shell
ES_JAVA_OPTS="-Xmx2g" DS_JAVA_OPTS="-Xmx1g" datashare <args>
```

As a rule of thumb, Elasticsearch typically needs more memory than Datashare (about twice as much).

## Where is Elasticsearch installed?

When you first launch Datashare, it automatically downloads and installs Elasticsearch in a platform-specific location:

| Platform | Path                                         |
| -------- | -------------------------------------------- |
| Linux    | `$HOME/.local/share/datashare/elasticsearch` |
| macOS    | `$HOME/Library/Datashare/elasticsearch`      |
| Windows  | `%APPDATA%\Datashare\elasticsearch`          |

On startup, Datashare launches Elasticsearch and waits for it to be ready. During this time, you may see log messages like:

```
INFO IndexWaiterFilter - Ping failed. Waiting for indexer to be up
```

This is normal. Once Elasticsearch is ready, you will see:

```
INFO IndexWaiterFilter - Ping indexer succeeded
```

## Troubleshooting

If Datashare or Elasticsearch fails to start, follow these steps:

1. **Run Elasticsearch on its own.** Go to the installation path listed above and start the `bin/elasticsearch` script manually to check if it runs properly.
2. **Run Datashare without Elasticsearch.** Launch Datashare without the `--elasticsearchPath` option so that it does not try to start Elasticsearch itself.
3. **Run both together.** If steps 1 and 2 succeed, close everything and launch Datashare normally.
4. **Check for Elasticsearch errors.** A common one is `exit 137`, which means Elasticsearch did not have enough memory to start.
5. **Adjust memory settings.** Try different values for `ES_JAVA_OPTS` and `DS_JAVA_OPTS` (see [above](#about-elasticsearch)).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://icij.gitbook.io/datashare/local-mode/about-the-local-mode/embedded-mode.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.