OpenAPI

To deploy BAML as a RESTful API, you’ll need to do three things:

• host your BAML functions in a Docker container
• update your app to call it
• run BAML and your app side-by-side using docker-compose

Read on to learn how to do this with docker-compose.

Host your BAML functions in a Docker container

In the directory containing your baml_src/ directory, create a baml.Dockerfile to host your BAML functions in a Docker container:

FROM node:20
WORKDIR /app
COPY baml_src/ .
# If you want to pin to a specific version (which we recommend):
# RUN npm install -g @boundaryml/baml@VERSION
RUN npm install -g @boundaryml/baml
CMD baml-cli serve --preview --port 2024

docker compose up --build --force-recreate

services:
  baml-over-http:
    build:
      # This will build baml.Dockerfile when you run docker-compose up
      context: .
      dockerfile: baml.Dockerfile
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:2024/_debug/ping" ]
      interval: 1s
      timeout: 100ms
      retries: 3
    # This allows you to 'curl localhost:2024/_debug/ping' from your machine,
    # i.e. the Docker host
    ports:
      - "2024:2024"
  debug-container:
    image: amazonlinux:latest
    depends_on:
      # Wait until the baml-over-http healthcheck passes to start this container
      baml-over-http:
        condition: service_healthy
    command: "curl -v http://baml-over-http:2024/_debug/ping"

To verify for yourself that BAML-over-HTTP is up and running, you can run:

curl http://localhost:2024/_debug/ping

Update your app to call it

Update your code to use BOUNDARY_ENDPOINT, if set, as the endpoint for your BAML functions.

import (
    "os"
    baml "my-golang-app/baml_client"
)
func main() {
    cfg := baml.NewConfiguration()
    if boundaryEndpoint := os.Getenv("BOUNDARY_ENDPOINT"); boundaryEndpoint != "" {
        cfg.BasePath = boundaryEndpoint
    }
    if boundaryApiKey := os.Getenv("BOUNDARY_API_KEY"); boundaryApiKey != "" {
        cfg.DefaultHeader["Authorization"] = "Bearer " + boundaryApiKey
    }
    b := baml.NewAPIClient(cfg).DefaultAPI
    // Use `b` to make API calls
}

Run your app with docker-compose

Replace debug-container with the Dockerfile for your app in the docker-compose.yaml file:

services:
  baml-over-http:
    build:
      context: .
      dockerfile: baml.Dockerfile
    networks:
      - my-app-network
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:2024/_debug/ping" ]
      interval: 1s
      timeout: 100ms
      retries: 3
    ports:
      - "2024:2024"
  my-app:
    build:
      context: .
      dockerfile: my-app.Dockerfile
    depends_on:
      baml-over-http:
        condition: service_healthy
    environment:
      - BAML_ENDPOINT=http://baml-over-http:2024
  debug-container:
    image: amazonlinux:latest
    depends_on:
      baml-over-http:
        condition: service_healthy
    command: sh -c 'curl -v "$${BAML_ENDPOINT}/_debug/ping"'
    environment:
      - BAML_ENDPOINT=http://baml-over-http:2024

Additionally, you’ll want to make sure that you generate the BAML client at image build time, because baml_client/ should not be checked into your repo.

This means that in the CI workflow you use to push your Docker images, you’ll want to do something like this:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build the BAML client
        run: |
          set -eux
          npx @boundaryml/baml generate
          docker build -t my-app .

(Optional) Secure your BAML functions

To secure your BAML server, you can also set a password on it using the BAML_PASSWORD environment variable:

BAML_PASSWORD=sk-baml-your-secret-password \
  baml-cli serve --preview --port 2024

This will require incoming requests to attach your specified password as authorization metadata. You can verify this by confirming that this returns 403 Forbidden:

curl -v "http://localhost:2024/_debug/status"

If you attach your password to the request, you’ll see that it now returns 200 OK:

export BAML_PASSWORD=sk-baml-your-secret-password
curl "http://baml:${BAML_PASSWORD}@localhost:2024/_debug/status"