Getting Started

This guide will walk you through deploying Mulberry, creating an account, generating API keys, and making your first API call.

1 Deploy

2 Account

3 API Keys

4 First Call

1. Deploy Mulberry

Mulberry is designed to run on your own infrastructure. The fastest way to get started is with Fly.io, which provides a simple deployment experience with built-in Postgres support.

Prerequisites

flyctl CLI installed

A Fly.io account

A domain name (optional, for custom domain)

Create Your App

Create a new directory for your Fly configuration and initialize the app:

Terminal

mkdir mulberry-fly && cd mulberry-fly
fly launch --image agoodway/mulberry_bot:latest --no-deploy

When prompted:

Choose your app name and region
Select "No" when asked about a Postgres database (we'll create it manually)

Create Postgres Database

Create a Fly Postgres database and attach it to your app:

Terminal

# Create a Postgres database
fly postgres create --name mulberry-db

# Attach it to your app (sets DATABASE_URL automatically)
fly postgres attach mulberry-db

Postgres Configuration

When prompted, choose "Development" for getting started. You can scale up later as needed.

Configure the App

Update the generated fly.toml to set the internal port:

fly.toml

[http_service]
  internal_port = 4000
  force_https = true
  auto_stop_machines = "stop"
  auto_start_machines = true

[env]
  PORT = "4000"
  PHX_HOST = "your-app-name.fly.dev"
  ECTO_IPV6 = "true"
  ERL_AFLAGS = "-proto_dist inet6_tcp"

Set Secrets

Generate and set the required secrets:

Terminal

# Generate and set SECRET_KEY_BASE
fly secrets set SECRET_KEY_BASE=$(openssl rand -base64 64 | tr -d '\n')

# Generate and set ENCRYPTION_KEY
fly secrets set ENCRYPTION_KEY=$(openssl rand -base64 32)

# Set your host
fly secrets set PHX_HOST="your-app-name.fly.dev"

# Set email configuration (required)
fly secrets set SMTP_HOST="smtp.postmarkapp.com"
fly secrets set MAIL_FROM="noreply@yourdomain.com"

Deploy

Deploy your app:

Terminal

fly deploy --image agoodway/mulberry_bot:latest

Run Migrations

Run database migrations:

Terminal

fly ssh console --command "/app/bin/migrate"

Useful Commands

Terminal

# Check deployment status
fly status

# View application logs
fly logs

# Open your app in browser
fly apps open

# SSH into your running app
fly ssh console

# Run an IEx session
fly ssh console --command "/app/bin/mulberry_bot remote"

# Deploy updates
fly deploy

IPv6 Networking

Fly.io uses IPv6 internally. The Dockerfile already includes the required ECTO_IPV6 and ERL_AFLAGS settings for proper database connectivity.

Environment Variables

Required

Variable	Description
`DATABASE_URL`	PostgreSQL connection URL. Set automatically by `fly postgres attach`
`SECRET_KEY_BASE`	Secret key for signing cookies and tokens. Generate with `openssl rand -base64 64`
`ENCRYPTION_KEY`	Base64-encoded 256-bit key for encrypting sensitive data at rest. Generate with `openssl rand -base64 32`
`SMTP_HOST`	SMTP server hostname for sending emails (e.g., `smtp.postmarkapp.com`)
`MAIL_FROM`	Email address used as the sender (e.g., `noreply@yourdomain.com`)

Optional

Variable	Default	Description
`PHX_SERVER`	-	Set to `true` to enable server mode for releases
`PORT`	`4000`	HTTP port the server listens on
`PHX_HOST`	`example.com`	Hostname for URL generation
`POOL_SIZE`	`10`	Database connection pool size
`ECTO_IPV6`	-	Set to `true` or `1` to enable IPv6 for database connections
`DNS_CLUSTER_QUERY`	-	DNS query for cluster discovery (libcluster)
`CORS_ORIGINS`	`https://example.com`	Comma-separated list of allowed CORS origins

Licensing (Pro Features)

These variables enable Pro license validation and encrypted credential storage.

Variable	Required	Description
`BLACKWALNUT_API_URL`	No	Base URL for the BlackWalnut licensing API (e.g., `https://blackwalnut.example.com`). Enables license validation and daily refresh.
`ENCRYPTION_KEY`	Yes (if using Pro features)	Base64-encoded 32-byte key for encrypting sensitive data. Generate with: `openssl rand -base64 32`

Generating Keys

Generate an ENCRYPTION_KEY with: openssl rand -base64 32

Email (Postmark)

Mulberry uses SMTP to send transactional emails (magic links, notifications). We recommend Postmark for reliable email delivery.

Variable	Required	Default	Description
`SMTP_HOST`	Yes	-	SMTP server hostname (`smtp.postmarkapp.com`)
`MAIL_FROM`	Yes	-	Default from email address (e.g., `noreply@yourdomain.com`)
`MAIL_FROM_NAME`	No	-	Display name for outgoing emails (e.g., `Mulberry`)
`SMTP_PORT`	No	`587`	SMTP server port
`SMTP_USERNAME`	No	-	SMTP authentication username (Postmark Server API Token)
`SMTP_PASSWORD`	No	-	SMTP authentication password (Postmark Server API Token)
`SMTP_SSL`	No	`false`	Enable SSL/TLS (`true` or `false`)
`SMTP_TLS`	No	`always`	TLS mode: `always`, `never`, or `if_available`

Setting Up Postmark

1 Create a Postmark account and set up a Server

2 Go to your Server → API Tokens and copy the Server API Token

3 Verify your sender signature (the email address you'll send from)

4 Set your Fly secrets:

Terminal

fly secrets set SMTP_HOST="smtp.postmarkapp.com"
fly secrets set SMTP_PORT="587"
fly secrets set SMTP_USERNAME="your-server-api-token"
fly secrets set SMTP_PASSWORD="your-server-api-token"
fly secrets set SMTP_TLS="always"
fly secrets set MAIL_FROM="noreply@yourdomain.com"
fly secrets set MAIL_FROM_NAME="Mulberry"

Note

Postmark uses the same Server API Token for both username and password.

2. Create Your Account

Once Mulberry is running, navigate to your server's URL and sign up for an account.

1 Visit https://your-app-name.fly.dev/

2 Click "Sign Up" or "Get Started"

3 Enter your email address

4 Check your email for a magic link (or set a password if password auth is enabled)

5 Click the link to complete registration

Tip

The first account created becomes the account owner with full administrative access.

3. Generate API Keys

API keys authenticate your requests to the Mulberry API. You can create keys from the dashboard.

1 Navigate to Settings → API Keys

2 Click "Create API Key"

3 Choose key type:

sk_ Private key – Full read/write access pk_ Public key – Read-only access

4 Give your key a descriptive name

5 Optionally set an expiration date

6 Copy the key immediately - it won't be shown again

Important

Store your API keys securely. Private keys provide full access to your account's crawl data and settings.

4. Make Your First API Call

Test your setup by listing your crawls (which will be empty initially):

Request

curl -H "Authorization: Bearer sk_your_api_key" \
  https://your-app-name.fly.dev/api/crawls

You should receive a response like:

Response

{
  "data": [],
  "meta": {
    "total": 0,
    "page": 1,
    "per_page": 20
  }
}

Now create your first crawl:

Request

curl -X POST \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "depth": 1}' \
  https://your-app-name.fly.dev/api/crawls

The response includes your new crawl's ID and status:

Response

{
  "data": {
    "id": "crawl_abc123",
    "url": "https://example.com",
    "status": "pending",
    "depth": 1,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Next Steps

Learn more about crawl options Explore all the ways to configure your crawls

Set up webhooks for real-time notifications Get notified when crawls complete

Connect AI agents via MCP Let Claude create crawls for you

Manage API keys and permissions Learn about key types and security