Deploy reflex app to Google cloud run

[jamesalphanome]

How to deploy a reflex app to google cloud build, how to set up both frontend and backend as separate containers and deploy ?

[jamesalphanome]

Have anyone done it before ?

[davidmuraya]

I have set it up as a single container on cloud build and cloud run. Let me know if that's what you would like.

[jamesalphanome]

Yes, that would be a great help. Ideally, I would want to deploy the frontend and backend on separate containers, to scale independently, but your setup would be very helpful. Thanks.

[davidmuraya]

Hi @jamesalphanome ,

My advice is based on many tests I have done on google cloud run.

My objective is to save on costs where I only want to be charged when processing requests (Request Based Billing on GCP Cloud Run).

I used the advice outlined here My approach is built on this, by building the image in multiple stages so as to create smaller, more optimized images.

The biggest issue I have had was trying to start the Reflex Backend Service as quickly as possible from a cold start. The recommended approach was taking too long. It was taking approx. 4 mins to start. By "recommended approach", I mean exec reflex run --env prod --backend-only

I am now running the backend service with Gunicorn and this has yielded better performance by starting the backend in 3 secs.

My dockerfile:

# This Dockerfile is used to deploy a single-container Reflex app instance to GCP, and others.

# If the service expects a different port, provide it here (i.e Render expects port 10000)
ARG PORT=8080
# Only set for local/direct access. When TLS is used, the API_URL is assumed to be the same as the frontend.
ARG API_URL

# It uses a reverse proxy to serve the frontend statically and proxy to backend
# from a single exposed port, expecting TLS termination to be handled at the
# edge by the given platform.
FROM python:3.13 as builder

RUN mkdir -p /app/.web
RUN python -m venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"

# Set dummy environment variables for the build process
ENV REFLEX_UPLOADED_FILES_DIR=assets/data/uploaded_files


WORKDIR /app

# Install python app requirements and reflex in the container
COPY requirements.txt .
RUN pip install -r requirements.txt


# Install reflex helper utilities like bun/fnm/node
COPY rxconfig.py ./
RUN reflex init

# Install pre-cached frontend dependencies (if exist)
COPY *.web/bun.lockb *.web/package.json .web/
RUN if [ -f .web/bun.lockb ]; then cd .web && ~/.local/share/reflex/bun/bin/bun install --frozen-lockfile; fi

# Copy local context to `/app` inside container (see .dockerignore)
COPY . .

ARG PORT API_URL
# Download other npm dependencies and compile frontend
RUN API_URL=${API_URL:-http://localhost:$PORT} reflex export --loglevel debug --frontend-only --no-zip
RUN mv .web/_static/* /srv/ && rm -rf .web


# Final image with only necessary files
FROM python:3.13-slim

# Install Caddy inside image
RUN apt-get update -y && apt-get install -y caddy curl && rm -rf /var/lib/apt/lists/*

ARG PORT API_URL
ENV PATH="/app/.venv/bin:$PATH" PORT=$PORT API_URL=${API_URL:-http://localhost:$PORT} PYTHONUNBUFFERED=1

WORKDIR /app
COPY --from=builder /app /app
COPY --from=builder /srv /srv

# Needed until Reflex properly passes SIGTERM on backend.
STOPSIGNAL SIGKILL

EXPOSE $PORT


RUN chmod +x /app/start.sh
ENTRYPOINT ["/app/start.sh"]

My start.sh file:

#!/bin/sh

# Start Gunicorn in the background
gunicorn --bind :8001 --workers 1 --worker-class uvicorn.workers.UvicornWorker --threads 4 -t 60 --max-requests 1000 --max-requests-jitter 50 app.app:app &

# Wait for Gunicorn to be ready (example with a ping check)
until curl -s http://127.0.0.1:8001/ping > /dev/null; do
    echo "Waiting for Gunicorn..."
    sleep 1
done

# Start Caddy in the foreground
exec caddy run

You may tweak this to your preference. I am starting the backend first, then serving the frontend after the backend starts successfully.

The only problem with this approach is that you will get the following errors which I have chosen to ignore for now:

2025-04-03 12:24:47 Traceback (most recent call last):
2025-04-03 12:24:47   File "/usr/local/lib/python3.13/concurrent/futures/_base.py", line 340, in _invoke_callbacks
2025-04-03 12:24:47     callback(self)
2025-04-03 12:24:47     ~~~~~~~~^^^^^^
2025-04-03 12:24:47   File "/app/.venv/lib/python3.13/site-packages/reflex/app.py", line 591, in <lambda>
2025-04-03 12:24:47     lambda f: f.result()
2025-04-03 12:24:47               ~~~~~~~~^^
2025-04-03 12:24:47   File "/usr/local/lib/python3.13/concurrent/futures/_base.py", line 449, in result
2025-04-03 12:24:47     return self.__get_result()
2025-04-03 12:24:47            ~~~~~~~~~~~~~~~~~^^
2025-04-03 12:24:47   File "/usr/local/lib/python3.13/concurrent/futures/_base.py", line 401, in __get_result
2025-04-03 12:24:47     raise self._exception
2025-04-03 12:24:47   File "/usr/local/lib/python3.13/concurrent/futures/thread.py", line 59, in run
2025-04-03 12:24:47     result = self.fn(*self.args, **self.kwargs)
2025-04-03 12:24:47   File "/app/.venv/lib/python3.13/site-packages/reflex/app.py", line 1361, in _compile
2025-04-03 12:24:47     self._get_frontend_packages(all_imports)
2025-04-03 12:24:47     ~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^
2025-04-03 12:24:47   File "/app/.venv/lib/python3.13/site-packages/reflex/app.py", line 945, in _get_frontend_packages
2025-04-03 12:24:47     prerequisites.install_frontend_packages(page_imports, get_config())
2025-04-03 12:24:47     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2025-04-03 12:24:47   File "/app/.venv/lib/python3.13/site-packages/reflex/utils/prerequisites.py", line 1235, in _inner
2025-04-03 12:24:47     func(*args, **kwargs)
2025-04-03 12:24:47     ~~~~^^^^^^^^^^^^^^^^^
2025-04-03 12:24:47   File "/app/.venv/lib/python3.13/site-packages/reflex/utils/prerequisites.py", line 1272, in install_frontend_packages
2025-04-03 12:24:47     primary_package_manager = install_package_managers[0]
2025-04-03 12:24:47                               ~~~~~~~~~~~

[jamesalphanome]

Thanks, @davidmuraya, I will give this a shot

[jamesalphanome]

Hi @davidmuraya,

Thanks for giving me the right direction. After some experimenting, I have below the best that have worked for me.

Dockerfile (for build speed and size):

# This Dockerfile is used to deploy a single-container Reflex app instance
# to services like Render, Railway, Heroku, GCP, and others.

# It uses a reverse proxy (caddy) to serve the frontend statically and proxy to backend
# from a single exposed port, expecting TLS termination to be handled at the
# edge by the given platform.


FROM python:3.13 AS builder

# If the service expects a different port, provide it here (f.e Render expects port 10000)
ARG PORT=8080
# Only set for local/direct access. When TLS is used, the API_URL is assumed to be the same as the frontend.
ARG API_URL
ARG uv=/root/.local/bin/uv

# Install `uv` for faster package bootstrapping
ADD --chmod=755 https://astral.sh/uv/install.sh /install.sh
RUN /install.sh && rm /install.sh

# Create virtualenv which will be copied into final container
RUN mkdir -p /app/.web
RUN $uv venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH"

WORKDIR /app

# Copy local context to `/app` inside container
COPY . .

# Install app requirements and reflex in the container
RUN $uv pip install -r requirements.txt

# Init app
RUN reflex init

# Install pre-cached frontend dependencies (if exist)
COPY *.web/bun.lockb *.web/package.json .web/
RUN if [ -f .web/bun.lockb ]; then cd .web && ~/.local/share/reflex/bun/bin/bun install --frozen-lockfile; fi

# Download other npm dependencies and compile frontend
RUN API_URL=${API_URL:-http://localhost:${PORT}} reflex export --frontend-only --no-zip && mv .web/_static/* /srv/ && rm -rf .web


# Final image with only necessary files
FROM python:3.13-slim

ARG PORT=8080
ARG API_URL

# Create a non-root user with a home directory
# RUN useradd -ms /bin/bash myuser
# USER myuser

# Install Caddy and redis server inside image
RUN apt-get update -y && apt-get install -y caddy redis-server curl && rm -rf /var/lib/apt/lists/*

# Copy the virtual environment from the builder stage
COPY --from=builder /app/.venv /app/.venv

ENV PATH="/app/.venv/bin:$PATH" PORT=$PORT API_URL=${API_URL:-http://localhost:${PORT}} PYTHONUNBUFFERED=1

WORKDIR /app
COPY --from=builder /app /app
COPY --from=builder /srv /srv
COPY Caddyfile /etc/caddy/Caddyfile

# Needed until Reflex properly passes SIGTERM on backend.
STOPSIGNAL SIGKILL

EXPOSE $PORT

# Start the backend.
RUN chmod +x /app/deploy.sh
ENTRYPOINT ["/app/deploy.sh"]

deploy.sh

#!/bin/sh

# cleanup
cleanup() {
  echo "Shutting down services..."
  
  # Stop Caddy if it's running
  if [ -n "$CADDY_PID" ] && kill -0 $CADDY_PID 2>/dev/null; then
    echo "Stopping Caddy..."
    kill $CADDY_PID 2>/dev/null || true
    wait $CADDY_PID 2>/dev/null || true
  fi
  
  # Stop Reflex if it's running
  if [ -n "$REFLEX_PID" ] && kill -0 $REFLEX_PID 2>/dev/null; then
    echo "Stopping Reflex backend..."
    kill -TERM $REFLEX_PID 2>/dev/null || true
    wait $REFLEX_PID 2>/dev/null || true
    echo "Reflex backend stopped."
  fi
  
  # Additional cleanup - find and kill any remaining processes
  pkill -f "reflex run" || true
  pkill -f "caddy" || true
  
  exit ${1:-0}  # Use provided exit code or default to 0
}

# Set up signal handling for various signals
trap 'cleanup 1' INT TERM
trap 'cleanup 0' EXIT  # This ensures cleanup happens on normal exit too

# Start Redis in the background
echo "Starting Redis..."
redis-server --daemonize yes

# Start Reflex backend in the background
echo "Starting Reflex backend..."
/app/.venv/bin/reflex run --env prod --backend-only &
REFLEX_PID=$!

# Wait for backend to be ready (with timeout)
echo "Waiting for Reflex backend to become ready..."
TIMEOUT=300  # seconds timeout
START_TIME=$(date +%s)

until curl -s http://localhost:8000/ping > /dev/null 2>&1; do
  CURRENT_TIME=$(date +%s)
  ELAPSED_TIME=$((CURRENT_TIME - START_TIME))
  
  if [ $ELAPSED_TIME -ge $TIMEOUT ]; then
    echo "Timed out waiting for backend to start (${ELAPSED_TIME}s elapsed)"
    cleanup 1
  fi
  
  # Check if reflex is still running
  if ! kill -0 $REFLEX_PID 2>/dev/null; then
    echo "Reflex backend failed to start"
    cleanup 1
  fi
  
  # REMAINING=$((TIMEOUT - ELAPSED_TIME))
  echo "Waiting for backend to be ready... (${ELAPSED_TIME}s elapsed)"
  sleep 15
done
echo "Backend is ready! Server serving..."

# Start Caddy in the foreground
echo "Starting Caddy..."
caddy run --config /etc/caddy/Caddyfile --adapter caddyfile
CADDY_PID=$!

# Check if Caddy started successfully
if ! kill -0 $CADDY_PID 2>/dev/null; then
  echo "Caddy failed to start"
  cleanup 1
fi

# keep it running
# wait $CADDY_PID || cleanup 1
wait $CADDY_PID
CADDY_EXIT=$?

wait $REFLEX_PID
REFLEX_EXIT=$?

if [ $CADDY_EXIT -ne 0 ] || [ $REFLEX_EXIT -ne 0 ]; then
  cleanup 1
else
  cleanup 0
fi

This setup have worked best for me. In Cloud run, the start up time is around 15s. I am waiting for the backend to start responding to ping then starting the caddy service.

I also have a gunicorn.conf.py file that sets some guicorn settings like threads,

bind = "0.0.0.0:8000"
workers = 3
worker_class = "uvicorn.workers.UvicornH11Worker"
threads = 2
timeout = 30
graceful_timeout = 15
max_requests = 800
max_requests_jitter = 50

Thanks.