Docker

Before connecting anything to Bubble, your Docker container needs to exist and expose a REST API. If you already have a running container deployed to a cloud platform with a public URL, skip to Step 3. If you are building from scratch, here is the minimal viable setup. For a Python FastAPI microservice, create a directory with these files: A 'main.py' with at least a health check endpoint and your business logic endpoint: ```python from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class ProcessRequest(BaseModel): data: str @app.get("/health") def health(): return {"status": "ok", "service": "my-bubble-service"} @app.post("/process") def process(request: ProcessRequest): # Your business logic here result = request.data.upper() # Example: return uppercased text return {"result": result, "length": len(request.data)} ``` A 'requirements.txt' with: fastapi and uvicorn[standard] A 'Dockerfile': ```dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . EXPOSE 8000 CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] ``` The `--host 0.0.0.0` is critical — binding to 0.0.0.0 makes the server accept connections from outside the container. Binding to 127.0.0.1 or localhost would make the container unreachable. Test locally with Docker to confirm it works before deploying to a cloud platform.

1FROM python:3.11-slim
2
3WORKDIR /app
4
5COPY requirements.txt .
6RUN pip install -r requirements.txt
7
8COPY . .
9
10EXPOSE 8000
11
12CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Bubble's API Connector requires a public HTTPS URL with a valid TLS certificate. A container running on your local machine is unreachable from Bubble's cloud servers. You must deploy to a cloud platform. Railway (railway.app) is the fastest path for developers who want to deploy a Docker container in minutes: 1. Create a Railway account and click 'New Project' 2. Choose 'Deploy from GitHub repo' or 'Empty project → Add a service → GitHub repo' 3. Railway auto-detects your Dockerfile and builds the container 4. Go to your service → Settings → Networking → Generate Domain — Railway assigns you a subdomain with automatic HTTPS and a valid TLS certificate 5. Note the URL: something like 'my-service-production.up.railway.app' Render (render.com) is another option: 1. Create a new Web Service → connect your GitHub repo or paste a Docker image URL 2. Render builds and deploys the container automatically 3. Your service gets a URL like 'my-service.onrender.com' with HTTPS For Node.js/Express services, the same pattern applies — the cloud platform wraps your container in HTTPS automatically. IMPORTANT security note: never expose the Docker Engine API (the socket at /var/run/docker.sock or TCP port 2375) publicly. Bubble's API Connector should never call the Docker Engine API on a publicly accessible endpoint — that gives remote code execution access to your entire host. Only expose your own application's REST API endpoints. After deployment, verify the URL works: open `https://your-service-url/health` in a browser. You should see your health check JSON response.

1# Railway CLI deployment (alternative to UI)
2npm install -g @railway/cli
3railway login
4railway init
5railway up
6# Your app will be deployed and Railway prints the public URL

In your Bubble editor, click the Plugins tab in the left sidebar. Click 'Add plugins', search for 'API Connector' (by Bubble), and install it. Click 'API Connector' in your Plugins list. Click 'Add another API' and name it based on your service (e.g., 'My Processing Service' or 'PDF Generator'). In the Shared headers section, add any authentication headers your Docker service requires. For example, if your service requires an API key header: Key: `X-API-Key`, Value: your API key, check the 'Private' checkbox. The Private flag ensures this key stays on Bubble's server and is never sent to the browser. If your Docker service requires Bearer token authentication: Key: `Authorization`, Value: `Bearer your-service-token`, check the 'Private' checkbox. If your service is publicly accessible without auth (internal tool with no sensitive data), you can skip the auth header. Now click 'Add another call'. Name it 'Health Check'. Set type to GET. Enter your URL: `https://your-service-url/health`. Set 'Use as' to 'Data'. Click 'Initialize call', then 'Send'. If you see your health check JSON response (e.g., `{"status": "ok", "service": "my-bubble-service"}`), Bubble will detect the fields — status (text) and service (text). A successful initialize confirms three things: (1) Bubble's servers can reach your Docker container's public URL, (2) the HTTPS certificate is valid and trusted, and (3) your auth headers are correct. If the initialize shows 'There was an issue setting up your call', check that the URL starts with https:// (not http://), that the service is running, and that no firewall blocks Bubble's cloud IP ranges from reaching your deployment.

1{
2  "method": "GET",
3  "url": "https://your-service-url/health",
4  "headers": {
5    "X-API-Key": "<your_api_key - Private>"
6  }
7}

With the health check confirmed, now add the API call for your primary business logic endpoint. Click 'Add another call' in your Docker service API group. For a POST endpoint (most processing services use POST): Name the call 'Process Data' (or whatever matches your endpoint). Set type to POST. Enter the full URL: `https://your-service-url/process`. Set 'Use as' to 'Action' (since this triggers processing, not loads data for display). Set the body type to 'JSON body'. Add the dynamic fields your endpoint expects: ```json { "data": "<input_data>", "user_id": "<user_id>", "options": { "format": "<output_format>" } } ``` Replace field names with what your API actually expects. The angled bracket fields like `<input_data>` become dynamic parameters Bubble will let you fill in at runtime. Click 'Initialize call'. Fill in test values for each dynamic parameter and click 'Send'. Your Docker service should process the test input and return a response. Bubble detects the response fields — for example, `result` (text), `processing_time_ms` (number), `pdf_url` (text). Now connect it to a Bubble Workflow. Go to the Workflow editor. Add or open a Workflow on a button click. Add a step: click 'Click here to add an action' → Plugins → 'Your Service Name - Process Data'. Map each parameter to Bubble dynamic values: - input_data: Input Element's value (or the Current User's data field) - user_id: Current User's unique ID - output_format: a hardcoded value or a Dropdown's value RapidDev's team has built Bubble apps with Dockerized ML models, PDF generators, and custom business logic APIs — for complex microservice architectures, book a free scoping call at rapidevelopers.com/contact. After the action step, add a conditional next step: 'Only when step 1 returned a result' — display the result in a Text element or save it to the Bubble database.

1{
2  "method": "POST",
3  "url": "https://your-service-url/process",
4  "headers": {
5    "X-API-Key": "<your_api_key - Private>",
6    "Content-Type": "application/json"
7  },
8  "body": {
9    "data": "<input_data>",
10    "user_id": "<user_id>",
11    "options": {
12      "format": "<output_format>"
13    }
14  }
15}

Production-grade Bubble + Docker integrations require explicit error handling for several failure modes: container cold starts, processing timeouts, and service errors. In every Workflow that calls your Docker service, add error handling steps: 1. After the API Connector action step, add a conditional action: 'Only when Step 1 has an error' (Bubble Workflow conditional). Show a user-facing error message: 'Processing failed — please try again in a moment.' 2. In your Docker container's FastAPI/Express code, always return structured error responses with HTTP status codes (400 for bad input, 500 for server errors) so Bubble can distinguish the failure type. The 30-second timeout is Bubble's hard limit for any Workflow step that calls an external API. If your Docker container's processing takes longer: Async job pattern implementation: 1. Add a POST /start-job endpoint that validates input, queues the job, and immediately returns `{"job_id": "uuid-here", "status": "queued"}` 2. Add a GET /job-status/{job_id} endpoint that returns the current status and result when complete 3. In Bubble: create a 'Job' data type with fields: job_id (Text), status (Text), result (Text), started_at (Date) 4. Step 1 Workflow: call POST /start-job → create a Job record with the returned job_id 5. Bubble's 'Schedule API Workflow' (paid plan required): set a recurring check every 10 seconds that calls GET /job-status/{job_id} for pending jobs 6. When the status returns 'complete', update the Job record and notify the user For health monitoring: on paid Bubble plans, you can create a Backend Workflow set to run on a recurring schedule — for example, every 5 minutes calling GET /health on your Docker service and creating a HealthLog record in Bubble's database if the response is not {"status": "ok"}.

1# Python FastAPI async job pattern
2from fastapi import FastAPI, BackgroundTasks
3import uuid
4
5app = FastAPI()
6jobs = {}  # In production, use Redis or a database
7
8@app.post("/start-job")
9async def start_job(request: ProcessRequest, background_tasks: BackgroundTasks):
10    job_id = str(uuid.uuid4())
11    jobs[job_id] = {"status": "queued", "result": None}
12    background_tasks.add_task(run_long_process, job_id, request.data)
13    return {"job_id": job_id, "status": "queued"}
14
15@app.get("/job-status/{job_id}")
16async def job_status(job_id: str):
17    if job_id not in jobs:
18        return {"status": "not_found"}
19    return {"job_id": job_id, **jobs[job_id]}
20
21async def run_long_process(job_id: str, data: str):
22    # Long-running work here
23    import asyncio
24    await asyncio.sleep(45)  # Simulates 45 seconds of processing
25    jobs[job_id] = {"status": "complete", "result": data.upper()}

Your Docker microservice is now callable from Bubble, but before going live, review security at both the Docker service level and the Bubble data layer. At the Docker service level: - Add API key authentication to all endpoints. The API key should be passed in a header (e.g., X-API-Key) and your service should return 401 if it is missing or invalid. Store the expected API key as an environment variable in your cloud platform (Railway: Variables tab; Render: Environment tab) — never hardcode it in the Dockerfile or source code. - Set CORS headers on your Docker service to restrict origins. Since Bubble's API Connector calls from Bubble's servers (not a browser), CORS is not technically required for the API Connector to work — but it is good practice if your service might ever be called from a browser context. - Ensure your service validates and sanitizes all input from Bubble before using it in database queries, shell commands, or ML model inference — treat Bubble's API calls as untrusted external input. At the Bubble level: - Go to Data tab → Privacy. For any Bubble data types that store results from your Docker service (e.g., ProcessingResult, PDFReport), set Privacy Rules to restrict which fields are visible to which users. At minimum: 'Find this in searches: When Current User's unique ID = Creator's unique ID' for user-specific results. - Ensure your Bubble app's logged-in state is checked before allowing users to trigger the Docker API call — use a Workflow condition 'Only when Current User is logged in' as a prerequisite step, or use Bubble's page access controls to require login before the page loads. - If the Docker service result includes sensitive data (financial reports, personal health data, etc.), consider storing only a reference (job_id, download_url) in Bubble's database and having the Docker service enforce access control on the result directly.

1# Railway/Render environment variable setup
2# Set these in your cloud platform's Variables/Environment settings:
3# API_KEY=your-long-random-api-key-here
4# DATABASE_URL=your-db-url-if-needed
5
6# In your FastAPI app, validate the key:
7from fastapi import Header, HTTPException
8import os
9
10API_KEY = os.getenv("API_KEY")
11
12def verify_api_key(x_api_key: str = Header(None)):
13    if x_api_key != API_KEY:
14        raise HTTPException(status_code=401, detail="Invalid API key")
15    return x_api_key