> For the complete documentation index, see [llms.txt](https://docs.aeternity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aeternity.com/developer-documentation/ae_mdw/docs/hyperchains_setup.md).

# AeMdw Hyperhain Setup Documentation

## Overview

AeMdw is a middleware that acts as a caching and reporting layer for the [æternity blockchain](https://github.com/aeternity/aeternity). It responds to queries more efficiently than the node and supports additional queries.

The middleware runs an Aeternity Node alongside it in the same Docker container and BEAM VM instance, so you don't need to run a standalone one. This node can be configured using the `aeternity.yaml` file or by passing environment variables, just like configuring the node directly.

## Step 1: Generating Configuration Files

To properly configure your middleware for Aeternity Hyperchains, start by generating the necessary configuration files from `init.hyperchains.ae`.

1. **Access the Hyperchains Initialization Tool**:
   * Visit [init.hyperchains.ae](https://init.hyperchains.ae/) in your web browser.
2. **Input Node Information and Generate the Configuration Files**:
   * Click on the 'Get Started' button.
   * Follow the on-screen instructions to enter details about your Hyperchain node and select a pinning chain.
   * Download the `init.yaml` file.
   * Follow the 'Next Steps' to generate additional configuration files:
     * `aeternity.yaml`
     * `${NAME}_accounts.json`
     * `${NAME}_contracts.json`

***

## Step 2: Running the Docker Container

Once you have the necessary configuration files, you can run the middleware using Docker:

```
docker run -it --name ae_mdw_${NAME} \
  -p 4000:4000 \
  -p 4001:4001 \
  -p 3113:3113 \
  -p 3013:3013 \
  -p 3014:3014 \
  -v ${PWD}/${NAME}/nodeConfig/aeternity.yaml:/home/aeternity/.aeternity/aeternity/aeternity.yaml \
  -v ${PWD}/${NAME}/nodeConfig/${NAME}_accounts.json:/home/aeternity/node/data/aecore/${NAME}_accounts.json \
  -v ${PWD}/${NAME}/nodeConfig/${NAME}_contracts.json:/home/aeternity/node/data/aecore/${NAME}_contracts.json \
  aeternity/ae_mdw
```

* **Make sure you have enough account balance on the pinning chain for all of the accounts**
* The command assumes the configuration files are in the `${NAME}/nodeConfig` directory in your current working directory, where `${NAME}` is the name of your Hyperchain.
* This command uses the [middleware image](https://hub.docker.com/r/aeternity/ae_mdw), which differs from the [node image](https://hub.docker.com/r/aeternity/aeternity).
* You can pass the `-d` flag to run the container in detached mode.

***

## Step 3: Persisting Node and Middleware Databases (Optional but Recommended)

To ensure data persistence across container restarts:

3. **Create the Data Directory** (if it doesn’t already exist):
   * In your working directory, create a `data` folder to store the node and middleware databases:

     ```
     mkdir -p ${PWD}/data
     ```
4. **Run the Docker Container with Volumes**:

```
docker run -it --name ae_mdw_${NAME} \
  -p 4000:4000 \
  -p 4001:4001 \
  -p 3113:3113 \
  -p 3013:3013 \
  -p 3014:3014 \
  -v ${PWD}/${NAME}/nodeConfig/aeternity.yaml:/home/aeternity/.aeternity/aeternity/aeternity.yaml \
  -v ${PWD}/${NAME}/nodeConfig/${NAME}_accounts.json:/home/aeternity/node/data/mnesia/${NAME}_accounts.json \
  -v ${PWD}/${NAME}/nodeConfig/${NAME}_contracts.json:/home/aeternity/node/data/mnesia/${NAME}_contracts.json \
  -v ${PWD}/data/mnesia:/home/aeternity/node/data/mnesia \
  -v ${PWD}/data/mdw.db:/home/aeternity/node/data/mdw.db \
  aeternity/ae_mdw
```

* `-v ${PWD}/data/mnesia:/home/aeternity/node/data/mnesia`: Persists the node database.
* `-v ${PWD}/data/mdw.db:/home/aeternity/node/data/mdw.db`: Persists the middleware database.

With this setup, the middleware will retain its state even after the container is stopped or restarted.

You can also pass the `-d` flag to run the container in detached mode.

## Step 4: Accessing the Middleware

Once the container is running, you can access the middleware at `http://localhost:4000` and the node at `http://localhost:3013`.

## Managing the Container

To check the logs, run the following command:

```
docker logs ae_mdw_${NAME}
```

To check the status of the container, run the following command:

```
docker ps -a
```

To stop the container, run the following command:

```
docker stop ae_mdw_${NAME}
```

To restart the container, run the following command:

```
docker start ae_mdw_${NAME}
```

***

## Node Configuration Options

You can use the same configuration options available for the Aeternity node to further customize your setup. For more information on available options and how to modify the `aeternity.yaml` file, refer to the [Aeternity node documentation](https://github.com/aeternity/aeternity).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.aeternity.com/developer-documentation/ae_mdw/docs/hyperchains_setup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.