> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Meilisearch

> Deploy the official Meilisearch Docker image on Upsun Cloud for fast, self-hosted search.

Deploy the official [Meilisearch](https://hub.docker.com/r/getmeili/meilisearch) image on Upsun Cloud using Docker image support.

For prerequisites and limitations, see [Self-hosted services from public Docker images](https://developer.upsun.com/docs/add-services/docker-images).

## Before you begin

1. [Install the Upsun Cloud CLI](https://developer.upsun.com/cli/install.md).
2. Run the following commands to log in and connect the current Git repository to the correct Upsun Cloud project. Replace `<PROJECT_ID>` with your project ID (run `upsun projects` to list them).

   ```bash theme={null}
   upsun login
   upsun auth:info
   upsun set-remote <PROJECT_ID>
   upsun project:info
   upsun environment:info
   ```

## 1. Configure Meilisearch as an app

Add the following configuration to `.upsun/config.yaml`.

* This configuration uses [the startup command defined by the image](https://developer.upsun.com/docs/add-services/docker-images#startup-commands). The official Meilisearch image already starts Meilisearch and listens on `0.0.0.0:7700`, so this example does not set `web.commands.start` to override it.
* The `/meili_data` mount maps to the path used by the official image for indexes, dumps, and snapshots.

```yaml theme={null}
applications:
  meilisearch:
    type: docker:1
    container_profile: HIGH_MEMORY

    # Pin the image tag for repeatable deploys. Avoid `latest` in production;
    # update this tag intentionally when you are ready to upgrade Meilisearch.
    image:
      name: "getmeili/meilisearch:v1.45.2"

    # Production baseline after deployment:
    #   upsun resources:set --size meilisearch:2 --disk meilisearch:10240
    # This keeps one Meilisearch instance with 2 CPU and, under HIGH_MEMORY,
    # roughly 4 GB RAM. Increase disk for larger indexes and snapshots.

    # /meili_data exists in the official image and is the documented Docker
    # volume path for Meilisearch data, dumps, and snapshots.
    mounts:
      "/meili_data":
        source: storage
        source_path: meili_data

    variables:
      env:
        # Production mode requires a valid MEILI_MASTER_KEY. Keep that key out
        # of Git and set it as a sensitive runtime variable instead:
        #   upsun variable:create --level environment --prefix env: --name MEILI_MASTER_KEY --value '<LONG_RANDOM_MASTER_KEY>' --sensitive true --visible-runtime true --visible-build false
        MEILI_ENV: "production"
        MEILI_DB_PATH: "/meili_data"

        # These are Meilisearch defaults relative to the Docker working
        # directory, but keeping them explicit makes backup/export locations
        # obvious and keeps the deployed runtime stable.
        MEILI_DUMP_DIR: "/meili_data/dumps"
        MEILI_SNAPSHOT_DIR: "/meili_data/snapshots"

        # The official image already binds to 0.0.0.0:7700. Keep this aligned
        # with web.upstream.socket_family: tcp and the route target below.
        MEILI_HTTP_ADDR: "0.0.0.0:7700"
        MEILI_NO_ANALYTICS: "true"

    web:
      upstream:
        # Meilisearch serves HTTP directly on a TCP port; passthrough lets the
        # Upsun Cloud router forward requests without expecting a local Unix socket.
        socket_family: tcp
      locations:
        "/":
          passthru: true

# This project does not need Upsun Cloud-managed services because Meilisearch is
# running as the app container itself.
services: null

routes:
  # Use a dedicated subdomain so clients can address Meilisearch directly.
  "https://meilisearch.{default}/":
    type: upstream
    upstream: "meilisearch:http"
```

## 2. Set or update the Meilisearch master key

Set `MEILI_MASTER_KEY` as a sensitive runtime environment variable instead of committing it to `.upsun/config.yaml`.

1. Generate a long random value for the master key:

   ```bash theme={null}
   openssl rand -hex 32
   ```

2. Use the generated value in place of `<LONG_RANDOM_MASTER_KEY>`:

   ```bash theme={null}
   upsun variable:create --level environment --prefix env: --name MEILI_MASTER_KEY --value '<LONG_RANDOM_MASTER_KEY>' --sensitive true --visible-runtime true --visible-build false
   ```

If the `MEILI_MASTER_KEY` variable already exists, update it:

```bash theme={null}
upsun variable:update env:MEILI_MASTER_KEY --level environment --value '<LONG_RANDOM_MASTER_KEY>' --sensitive true --visible-runtime true --visible-build false
```

## 3. Deploy the app

Commit the changes to `.upsun/config.yaml` and push them to Upsun Cloud:

```bash theme={null}
git add .upsun/config.yaml
git commit -m "Add Meilisearch Docker image app"
upsun push
```

## 4. Allocate Meilisearch resources

The first deployment [defaults to a minimal resource allocation](https://developer.upsun.com/docs/manage-resources/resource-init.md) regardless of app type (0.5 CPU, 512 MB disk, and [1408 MB memory](https://developer.upsun.com/docs/manage-resources/adjust-resources.md#shared-cpu-container-sizes)). That's enough to boot the container, but not to handle real indexing and search traffic, so set a production baseline for the app:

```bash theme={null}
upsun resources:set --size meilisearch:2 --disk meilisearch:10240
```

With `container_profile: HIGH_MEMORY`, the Meilisearch app gets 2 CPU, about 4 GB RAM, 10 GB disk, and one instance. If your indexes, dumps, or snapshots grow past that, [increase the disk size](https://developer.upsun.com/docs/manage-resources/adjust-resources.md#vertical-scaling).

If you changed resources after the app was already deployed, redeploy the environment:

```bash theme={null}
upsun environment:redeploy
```

## 5. Validate the deployment

List the routes, and confirm that the HTTPS route mapped to the `meilisearch` app appears. You'll use it in place of `<MEILISEARCH_ROUTE>` in the next step.

```bash theme={null}
upsun route:list
```

Check the health endpoint. Replace `<MEILISEARCH_ROUTE>` with the HTTPS route for the Meilisearch app:

```bash theme={null}
curl https://<MEILISEARCH_ROUTE>/health
```

Expected response:

```json theme={null}
{"status":"available"}
```

If the health check doesn't return this, or you run into other issues deploying the app, [debug the app over SSH](https://developer.upsun.com/docs/add-services/docker-images#debug-an-app-over-ssh) to check `/var/log/app.log` and the container's process state.

## Updating the image version

To use a different Meilisearch version, update the version in `image.name`:

```yaml theme={null}
applications:
  meilisearch:
    type: docker:1
    image:
      name: "getmeili/meilisearch:<VERSION>"
```

Then, commit and push the change:

```bash theme={null}
git add .upsun/config.yaml
git commit -m "Update Meilisearch image version"
upsun push
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.