Forem: Florian Flock

Serverless Next.js with Google Cloud Run

Florian Flock — Sat, 22 Jan 2022 19:16:08 +0000

Introduction

Serverless is one of the many buzzwords since cloud technologies have been around. What it means exactly and for which applications it is best suited is beyond the scope of my blog post. However, I would like to warmly recommend an O'Reilly book with the title Learning Serverless.

In the area of frontend development, I have been working with Next.js for some time. The framework enables server-side rendering of React websites and also offers some performance improvements. Next.js is hosted in Node environments, so it offers the highest possible flexibility. Especially for volatile frontends, a serverless infrastructure is best suited for hosting.

The official documentation of Next.js includes an example with Firebase Hosting. The main disadvantage is that the dynamic part of the application is executed on Cloud Functions which comes with many limitations. For example, the next/image optimisation package is not usage because of limited support.

In the following blog post, I explain how Next.JS can be hosted on Google Cloud Run. In addition to Cloud Run, static files are provided via Firebase. Firebase thus serves as a proxy and CDN at the same time.

Prerequisites

Understanding and Knowledege of Next.js
Up and running Google Cloud Project with billing enabled
Artifact Registry enabled on Google Cloud
Basic understanding in Google Cloud Run and Firebase
Basic understanding of Bitbucket Pipelines or other CI/CD tools

Additionally, please read through the Google documentation regarding Cloud Run and Custom Domains with Firebase. Recently, custom domains are supported for Cloud Run as well, without a firebase application. However, it does not work as expected since it is still in preview. However, there are some additional advantages with upfront Firebase Hosting.

Have a look on the Firebase documentation page as well where they describe how to enable Cloud Run as a dynamic backend for Firebase Hosting.

Process Overview

Prepare your git repository with a Next.js app included.
Get your CI/CD pipeline ready. I went for Bitbucket Pipelines, you can use the tool of your choice, even executing everything manually is possible.
Execute the pipeline step or do it manually on your Notebook.
Create your first Cloud Run Revision to make sure all settings are correct, see my learnings below.
Add a custom domain.

Application Structure

My Next.js application is already somewhat more extensive. Among other things, it is multilingual and connected to several backend APIs. Furthermore, I decided to use TypeScript from the beginning.

|-- Dockerfile
|-- README.md
|-- bitbucket-pipelines.yml
|-- components
|-- config
|-- contexts
|-- dist
|-- firebase.json
|-- global.d.ts
|-- hooks
|-- interfaces
|-- models
|-- next-env.d.ts
|-- next-i18next.config.js
|-- next.config.js
|-- node_modules
|-- package.json
|-- pages
|-- providers
|-- public
|-- reducers
|-- tsconfig.json
|-- utils
`-- yarn.lock

Next.js Config

Before we start, I want to share my next.config.js. It does include some improvements. But I want you to pay attention to the distDir. Normally, the application builds into the folder .next. For some reason, I rewrite it to dist. The built folder is referenced in the Dockerfile later on.

require('dotenv').config()

const withPlugins = require('next-compose-plugins')
const nextFonts = require('next-fonts')
const { i18n } = require('./next-i18next.config')

// @ts-check
/**
 * @color {import('next').Config}
 */
const nextConfig = {
  reactStrictMode: true,
  i18n,
  cssModules: true,
  cssLoaderOptions: {
    importLoaders: 1,
    localIdentName: '[local]___[hash:base64:5]'
  },
  images: {
    domains: ['checkoutshopper-live.adyen.com']
  },
  optimizeFonts: true,
  distDir: './dist',
  publicRuntimeConfig: {
    apiUrl: process.env.API_URL,
    adyenEnvironment: process.env.ADYEN_ENVIRONMENT
  }
}

module.exports = withPlugins([
  [nextFonts]
], nextConfig)

Firebase

As you might already have read through the articles in the blog post, you are familiar with the json structure of firebase.json.

It basically says that all the dynamic traffic gets proxied to the Cloud Run service with the name frontend hosted in the region europe-west6.

{
  "hosting": {
    "site": "your-company-frontend",
    "public": "public",
    "rewrites": [
      {
        "source": "**",
        "run": {
          "serviceId": "frontend",
          "region": "europe-west6"
        }
      }
    ]
  }
}

Multi-Stage Dockerfile

The heart of the process is a huge multi-stage Dockerfile. If you did not heard anything about Docker multi-stage builds, I would highly recommend the official documentation.

Base Image with Build Dependencies

I prepared an image based on alpine with pre-installed node 17. It just adds some dependencies which are needed for building the Next.js application. Just to notice: It was a real pain to get all necessary packages in a list, it took many hours.

Install Yarn Dependencies

This stage just installs the necessary packages with Yarn. We later refer on the stage as deps.

Build the Next.js Application

We continue with building the Next.js application with yarn build. Take care that you build your application with production data, e.g. .env file with production-ready content.

Production Image

This stage of the Dockerfile is the main image which is later running on Google Cloud Run. I decided to create a non-root user for the main process for security reasons. Afterwards, all necessary files are copied from the previous build steps.

Management Image for Firebase Deploy

On the top end of the file, I created another step for the firebase deployment. The stage is used in the pipeline later on.

################################################
### Base Image with Build Dependencies       ###
################################################
FROM node:17-alpine AS base

RUN apk add --update --no-cache \
    build-base \
    autoconf \
    automake \
    libtool \
    shadow \
    gcc \
    musl-dev \
    make \
    tiff \
    jpeg \
    zlib \
    zlib-dev \
    file \
    pkgconf \
    g++ \
    libc6-compat \
    libjpeg-turbo-dev \
    libpng-dev \
    libwebp-tools \
    nasm

WORKDIR /app

################################################
### Install Yarn Dependencies                ###
################################################
FROM base AS deps

WORKDIR /app

COPY package.json yarn.lock ./

RUN yarn install --frozen-lockfile

################################################
### Build the Next.js Application            ###
################################################
FROM base AS builder

WORKDIR /app

COPY . .
RUN mv /app/.env.production /app/.env
COPY --from=deps /app/node_modules ./node_modules

ENV NODE_ENV production

RUN yarn build

################################################
### Production Image                         ###
################################################
FROM node:17-alpine AS runner

WORKDIR /app

ENV NODE_ENV production

# Create a non-root user for runtime
RUN addgroup -g 1001 -S nodejs
RUN adduser -S nextjs -u 1001

# You only need to copy next.config.js if you are NOT using the default configuration
COPY --from=builder /app/next.config.js ./
COPY --from=builder /app/next-i18next.config.js ./
COPY --from=builder --chown=nextjs:nodejs /app/dist ./dist

# firebase caches the /public/ folder and set it to the root.
COPY --from=builder --chown=nextjs:nodejs /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/dist/static ./public/_next/static

# Copy rest of the files from the builder
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
COPY --from=builder /app/.env ./.env

USER nextjs

ENV PORT 3000

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry.
# ENV NEXT_TELEMETRY_DISABLED 1

CMD ["node_modules/.bin/next", "start"]

################################################
### Management Image for Firebase Deploy     ###
################################################
FROM node:14-alpine as firebase-deploy
RUN npm install -g firebase-tools

WORKDIR /app

# Copy all necessary files to be recognzied by firebase
COPY --from=builder /app/firebase.json ./firebase.json
COPY --from=builder /app/.firebaserc ./.firebaserc
COPY --from=builder /app/public ./public
# Copy static files from next.js build into the public folder
# to be recognized by the CDN of Firebase.
COPY --from=builder /app/dist/static ./public/_next/static

CMD ["/bin/sh", "-c", "firebase deploy"]

Bitbucket Pipeline

Let us move on to the Pipeline. Years ago, I decided to use Bitbucket Pipelines because most of my source code is hosted on Bitbucket as well. I would recommend getting familiar with the structure of the YAML file bitbucket-pipelines.yml in the documentation.

The first part of the deployment step is all about authorization to the Google Cloud. As you might have recognized, I use the image google/cloud-sdk:latest as a base image during the deployment. As you can see, the first line of the step requires a Environment Variable GCLOUD_CREDENTIALS. You have to add it in the Bitbucket Pipelines interface and basically, it is a GCP Service Account as base64 string. The service account should have the proper access rights to push the image, deploy the cloud run revision and execute the firebase command.

The second part of the step is building the docker image and push it to the Artifact Registry.

The last pipeline-managed thing is to deploy the new image as an Cloud Run revision in order to update the entire application.

There is even a very last step: The previously shown stage in the Dockerfile for the firebase deployment gets build and executed as one-off container, just to deploy the firebase frontend.

definitions:
  services:
    docker:
      memory: 3072
  steps:
    - step: &build-and-push-cloudrun-app
        name: Build Cloud Run Application
        image: google/cloud-sdk:latest
        caches:
          - docker
        services:
          - docker
        script:
          - echo $GCLOUD_CREDENTIALS | base64 --decode --ignore-garbage > ./gcloud-api-key.json
          - gcloud auth activate-service-account --key-file gcloud-api-key.json
          - gcloud config set project $GCLOUD_PROJECT
          - gcloud auth configure-docker europe-west3-docker.pkg.dev --quiet
          - rm ./gcloud-api-key.json

          - export IMAGE_NAME=europe-west3-docker.pkg.dev/$GCLOUD_PROJECT/cloud-run/frontend

          - docker build -t $IMAGE_NAME:v$BITBUCKET_BUILD_NUMBER --target runner .
          - docker tag $IMAGE_NAME:v$BITBUCKET_BUILD_NUMBER $IMAGE_NAME:latest
          - docker push $IMAGE_NAME:v$BITBUCKET_BUILD_NUMBER && docker push $IMAGE_NAME:latest

          - |
            gcloud run deploy frontend \
            --async \
            --image=$IMAGE_NAME:v$BITBUCKET_BUILD_NUMBER \
            --region=europe-west6 \
            --project=$GCLOUD_PROJECT

          - docker build -t firebase-deploy --target firebase-deploy .
          - docker run --rm -e FIREBASE_TOKEN=$FIREBASE_TOKEN firebase-deploy
pipelines:
  branches:
    master:
      - step: *build-and-push-cloudrun-app

Custom Domain

If everything has been deployed correctly, you should be able to reach the application via the url which is provided by Firebase. Now you can add the custom domain described here.

Important Learnings

I would recommend creating the first Cloud Run revision by yourself in the user interface. Please ensure that you have at least one container running to avoid long cold starts.

I learned a lot about cold starts and the performance of Cloud Run instances by reading the community-maintained FAQ repository.

Conclusion

The serverless frontend gives us the huge opportunity to allocate resources only when necessary and even scale from zero. We have seen huge cost and performance improvements.

Enable feature-rich Logging for FastAPI on Google Cloud Logging

Florian Flock — Sat, 22 Jan 2022 17:19:29 +0000

Introduction

I recently evaluated some of the typical Python web frameworks for a small REST API project. Previously I worked with Flask, but something caught me to try another framework this time. To put it very briefly - this time, I decided to use FastAPI, a modern and high-speed framework for use with REST APIs. FastAPI also has other advantages. For example, the documentation of the endpoints is already automatically generated in OpenAPI format and output as a Swagger interface. Smart!

Many voices and experts also see FastAPI as an emerging framework. So it's time to give it a try.

// Detect dark theme var iframe = document.getElementById('tweet-1484770851367309313-358'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1484770851367309313&theme=dark" }

Since many of my provided services are already running in the Google Cloud, it was evident for this project to fall back on the hosting services there. New framework and new infrastructure would feel overwhelming.

My project, in this case, processes huge loads of financial data, and accordingly, I wanted to make sure that the logging of activities is clean and traceable. Sometimes I need to reproduce step by step the processors to understand where adaptions to the business logic are required.

Google Cloud Logging

Google Cloud offers a product called Google Cloud Logging for logging and tracing. All log entries are collected centrally and retrieved using a custom query language.

With most hosting options in the Google Cloud, the log entries are collected and processed via Fluentd. Google provides documentation for a JSON object of the optimal log entry. One of our goals would be to meet the requirements of this object.

In addition, clients are provided by google for the most common programming languages that convert log entries into the format shown above.

pip install google-cloud-logging

In the case of Python, the Django and Flask frameworks are natively supported by the client. For both frameworks, the client converts a lot of data into the proper format, especially the severity level and the trace of the request. Django and Flask benefit from built-in framework recognition by the google client. Have a look on the specific code piece.

However, FastAPI is a pretty new framework and does not have any built-in support from the logging client. The log entries are loosely coupled, and Google Cloud Logging does not correctly show even the severity of the log entries:

I tried to modify my logging accordingly to ensure better traceability of the log entries.

Enable Log Tracing

One of the main objectives was to include the so-called trace ID for each log entry. This ID enables the log entries to be linked to the respective request. The additional information makes it possible to trace which request caused the log entry. It is particularly advantageous when the REST API is under heavy traffic, and errors or warnings should be reproduced.

I know that there are tools like OpenTelemetry. Even Google suggests OpenTelemetry in their docs. But for most applications, in my opinion, this is over-engineering, especially for stand-alone applications (not chained in a micro service architecture).

However, if applications are hosted with the App Engine, Cloud Functions or Cloud Run on Google Cloud, the GCP proxy/load balancer technology adds a special incoming request header:

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=TRACE_TRUE

I recommend the further reading about the trace log integration. We will use this header information to link the log entries as already discussed.

File Structure

I decided to create a directory called cloud_logging. At this point it should be mentioned that the folder is deliberately not only called logging as there may be complications with the build-in packages of the same name.

The structure after setup of FastAPI and my logging adaptation looks like this:

|-- Dockerfile
|-- cloud_logging
|   |-- __init__.py
|   |-- filter.py
|   |-- middleware.py
|   `-- setup.py
|-- main.py
|-- readme.md
`-- requirements.txt

One day, I will publish the source code as a published python package or try to make a pull request to the google logging client for the native integration.

Middleware

Let us start with the middleware. This class implements the BaseHTTPMiddleware class provided by Starlette and is mainly used to provide additional logic for all incoming requests. Starlette is shipped with FastAPI and it is the underlying ASGI framework.

Essentially, two important things are done here. Firstly, essential information about the request is written into a Python dictionary. Secondly, it checks whether the previously mentioned header is available.

Both pieces of information are processed and written into context variables. We use these variables later in the filter.

The finished middleware then looks like this:

import contextvars
import sys

from fastapi.logger import logger
from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
from starlette.requests import Request
from starlette.responses import Response, JSONResponse

cloud_trace_context = contextvars.ContextVar('cloud_trace_context', default='')
http_request_context = contextvars.ContextVar('http_request_context', default=dict({}))


class LoggingMiddleware(BaseHTTPMiddleware):
    async def dispatch(
            self, request: Request, call_next: RequestResponseEndpoint
    ) -> Response:
        if 'x-cloud-trace-context' in request.headers:
            cloud_trace_context.set(request.headers.get('x-cloud-trace-context'))

        http_request = {
            'requestMethod': request.method,
            'requestUrl': request.url.path,
            'requestSize': sys.getsizeof(request),
            'remoteIp': request.client.host,
            'protocol': request.url.scheme,
        }

        if 'referrer' in request.headers:
            http_request['referrer'] = request.headers.get('referrer')

        if 'user-agent' in request.headers:
            http_request['userAgent'] = request.headers.get('user-agent')

        http_request_context.set(http_request)

        try:
            return await call_next(request)
        except Exception as ex:
            logger.debug(f'Request failed: {ex}')
            return JSONResponse(
                status_code=500,
                content={
                    'success': False,
                    'message': ex
                }
            )

Logging Filter

After that, it is necessary to implement a logging filter. The following filter implements the CloudLoggingFilter provided in the Google Cloud Logging Library. We overwrite the filter method, which is called for each log entry. The main task of the filter is to append the information according to the Google Cloud Logging format to the record that was previously fetched by the middleware. The trace header still needs a little processing.

The finished filter looks like this:

import logging
import re

from google.cloud.logging_v2.handlers import CloudLoggingFilter

from cloud_logging.middleware import http_request_context, cloud_trace_context


class GoogleCloudLogFilter(CloudLoggingFilter):

    def filter(self, record: logging.LogRecord) -> bool:
        record.http_request = http_request_context.get()

        trace = cloud_trace_context.get()
        split_header = trace.split('/', 1)

        record.trace = f"projects/{self.project}/traces/{split_header[0]}"

        header_suffix = split_header[1]
        record.span_id = re.findall(r'^\w+', header_suffix)[0]

        super().filter(record)

        return True

Setup

Last but not least, we have to make sure that the Python logger executes the desired logic. For this purpose, I have written a setup method called when the FastAPI application is started.

Essentially, this connects the logger provided by Python to Google Cloud Logging and our filter:

import logging

import google.cloud.logging

from cloud_logging.filter import GoogleCloudLogFilter
from fastapi.logger import logger


def setup_logging():
    client = google.cloud.logging.Client()
    handler = client.get_default_handler()
    handler.setLevel(logging.DEBUG)
    handler.filters = []
    handler.addFilter(GoogleCloudLogFilter(project=client.project))
    logger.handlers = []
    logger.addHandler(handler)
    logger.setLevel(logging.DEBUG)

Main Application

When starting the FastAPI application, adding the middleware and executing the setup method are necessary. I have decided to use Google Cloud Logging only in the production environment; locally, the standard logger is used.

The main application could then look something like this (main.py):

import logging
from fastapi import FastAPI
from fastapi.logger import logger
from pydantic import BaseSettings
from cloud_logging.middleware import LoggingMiddleware
from cloud_logging.setup import setup_logging


class Settings(BaseSettings):
    environment: str = 'development'


settings = Settings()
app = FastAPI()

if settings.environment == 'production':
    setup_logging()
    app.add_middleware(LoggingMiddleware)
else:
    logger.setLevel(logging.DEBUG)


@app.get('/')
async def root():
    logger.debug('DEBUG LOG')
    logger.error('ERROR LOG')
    logger.warning('WARNING LOG')
    logger.info('INFO LOG')
    return {'message': 'Hello World'}

After re-deploying the application to Google Cloud Run, the log entries looks much better.

Conclusion

Clean log entries are one of the most important things for me when developing robust applications. Even though the process described here is not yet perfect, the log entries in the Google Cloud interface look excellent. And with the help of the trace, the log entries that belong together can now be analyzed.

Dockerfile

Just to make the things complete in the blog post, I will share my Dockerfile. The image is optimized for the usage on Google Cloud Run. The environment variable PORT is always set when using Cloud Run.

FROM python:3.9-slim

WORKDIR /app

COPY requirements.txt /app/requirements.txt

RUN pip install -r /app/requirements.txt

COPY . /app

CMD exec gunicorn --bind :$PORT --workers 1 --worker-class uvicorn.workers.UvicornWorker  --threads 8 main:app

Cover Photo by Chris Ried on Unsplash