Skip to content

🌐 API Instance

The Meerschaum API instance (and Web Console) lets you manage pipes, jobs, and connectors over the Internet. Start the API server with the stack or via start api; see Deployment below for ways to run Meerschaum in production.

Usage

Starting the Meerschaum API server lets you treat your host as the following:

Adding Connectors

Add new api connectors with bootstrap connector or declaring an environment connector:

# URI is in the form 'protocol://user:pass@host:port'
export MRSM_API_FOO='https://foo:bar@mrsm.example.com'

Remote Actions

Add -e to client commands to execute them remotely on your API instance:

sync pipes -e api:main

When running the mrsm shell, the executor command allows you to temporarily run all the commands in your session remotely (like the instance command):

executor api:main

API Documentation

You can visit your API instance's Swagger documentation by navigating to /docs or /redoc.

Deployment

It's common in production deployments to stand up a public-facing API instance. See below for deployment tips:

Meerschaum Stack (easiest)

If you have Docker installed, the most straightforward way to deploy is via the Meerschaum stack:

mrsm stack up -d

This starts an internally-managed, pre-configured Docker Compose project with an api service that runs on http://localhost:8000.

The environment in the api service is updated such that connectors from your host are passed to the container.

Want to manage Docker yourself?

You can run the bmeares/meerschaum Docker image if you'd like to add Meerschaum to another Docker Compose project. You may also edit the stack Docker Compose project with mrsm edit config stack under the key docker-compose.yaml.

Bare Metal

If you don't want to deploy with Docker, you can run an API instance on your host directly:

The --production flag starts the API server with gunicorn, allowing for self-healing.

mrsm start api --production

For example, this is a common pattern for standing up a systemd service to start the API server:

mrsm start api --production --name api-instance -d

TLS / SSL / HTTPS

See the example NGINX configuration for a proxy pass to add HTTPS to your API instance via Let's Encrypt.

Otherwise, if you have a certificate on hand, you can run the API server with --keyfile and --certfile:

mrsm start api --keyfile /path/to/key --certfile /path/to/cert

Docker

If you're building your own Docker images, consider basing off the bmeares/meerschaum Docker image, as is done in the mrsm compose template repository:

FROM bmeares/meerschaum

RUN mrsm install plugin compose
COPY --chown=meerschaum:meerschaum ./ /app
WORKDIR /app
RUN mrsm compose init

ENTRYPOINT ["/app/docker/bootstrap.sh"]

This image comes pre-installed with common database drivers and package dependencies. Note this image is configured to run as a non-privileged user meerschaum.

Of course, you can always pip install Meerschaum into your own custom image:

FROM python

# Install dependencies into the virtual environment:
RUN pip install meerschaum && mrsm upgrade packages api -y

# or to install dependencies globally:
# RUN pip install meerschaum[api]

ENTRYPOINT ["python", "-m", "meerschaum"]

AWS

Run the bmeares/meerschaum Docker image with ECS or on an EC2 like you would any other Docker container. See the Docker section above if you want to build your own images.

Helm Chart (k8s)

If you are running Kubernetes, consider the Meerschaum Helm chart on Artifact Hub. It's configured to run the bmeares/meerschaum Docker Image for k8s environments.