Skip to content

🥞 Meerschaum Stack

The Meerschaum stack is an integrated collection of services designed to help you start visualizing your data as quickly as possible.

The stack command wraps Docker Compose to create a full-stack Meerschaum installation ― services such as a database instance, API server, and pre-configured Grafana instance.

🐳 Services

The default stack starts 4 services:

Service Description Image
db TimescaleDB instance corresponding to sql:main. timescale/timescaledb:latest-pg16-oss
api Production Meerschaum Web API server corresponding to api:main. bmeares/meerschaum:api
valkey Valkey instance corresponding to valkey:main. Used for caching sessions in by api. bitnami/valkey:latest
grafana Grafana instance connected to sql:main. grafana/grafana:latest

You can edit the stack's Docker Compose file with mrsm edit config stack.

Entering the Meerschaum Docker image

Hop into a shell in the api service:

1
mrsm stack exec -it api mrsm

You may want to run bash instead:

1
mrsm stack exec -it api bash

🗒️ Requirements

You need Docker installed to run the stack. To install Docker, follow this guide or do the following:

Install Docker Desktop.

Search your repositories for docker.io or run this script:

1
curl https://get.docker.com | sh

Don't forget to add yourself to the docker user group and log out and back in.

1
sudo usermod -aG docker myusername

🟢 Starting the Stack

Run the following command to bring up a database and Grafana:

1
mrsm stack up -d db grafana

The stack command is a wrapper around a pre-configured docker-compose project. Don't worry if you don't have docker-compose installed; in case it's missing, Meerschaum will automatically install it within a virtual environment for its own use.

Refer to the docker-compose overview page to see the available stack commands.

Example Grafana Dashboard

Grafana is included in the Meerschaum stack, pre-configured with the Meerschaum TimescaleDB database.

Open a web browser and navigate to http://localhost:3000 where you can log into Grafana with username admin, password admin.

🛑 Stopping the Stack

If you want to stop all the services in the stack, run the stack command with down:

1
mrsm stack down

To remove all services in the stack and delete all data, use the -v flag:

1
mrsm stack down -v

Data Loss Warning

The -v flag in stack down -v will delete ALL volumes in the stack. That includes pipes' data!

To delete a specific service's volume, run the command docker volume rm, e.g. to delete just Grafana's data: 

1
docker volume rm mrsm_grafana_storage

📝 Editing the Stack

Certain parameters like the main database username and password are linked from the connectors configuration, which may be accessed with mrsm edit config.

You can find the complete Docker Compose YAML file with:

1
mrsm edit config stack