> ## Documentation Index
> Fetch the complete documentation index at: https://www.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy a Global, Serverless Application

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

This page guides you through deploying an application and database in multiple regions. It is the fifth and final section of the <InternalLink path="movr#develop-and-deploy-a-global-application">Develop and Deploy a Global Application</InternalLink> tutorial.

## Before you begin

Before you begin this section, complete the previous section of the tutorial, <InternalLink path="movr-flask-application">Develop a Multi-Region Web Application</InternalLink>. After you finish developing and debugging your multi-region application in a local development environment, you are ready to deploy the application and database in multiple regions.

In addition to the requirements listed in <InternalLink path="movr-flask-setup">Setting Up a Virtual Environment for Developing Multi-Region Applications</InternalLink>, make sure that you have the following:

* [A Google Cloud account](https://cloud.google.com/)
* [The Google Cloud SDK installed on your local machine](https://cloud.google.com/sdk/install)
* [Docker installed on your local machine](https://docs.docker.com/v17.12/docker-for-mac/install)

## Multi-region database deployment

In production, you want to start a secure CockroachDB cluster, with nodes on machines located in different areas of the world. To deploy CockroachDB in multiple regions, we recommend using <InternalLink version="cockroachcloud" path="quickstart">CockroachDB Standard</InternalLink>.

<Note>
  You can also deploy CockroachDB manually. For instructions, see the <InternalLink path="manual-deployment">Manual Deployment</InternalLink> page of the Cockroach Labs documentation site.
</Note>

### Create a multi-region CockroachDB Standard cluster

1. [Sign up for a CockroachDB Cloud account](https://cockroachlabs.cloud/signup?referralId=docs_movr_global).
2. [Log in](https://cockroachlabs.cloud/) to your CockroachDB Cloud account.
3. On the **Overview** page, select **Create Cluster**.
4. On the **Create new cluster** page:
   * For **Plan**, select CockroachDB Standard. You won't be charged for the first 30 days of service.
   * For **Cloud Provider**, select Google Cloud.
   * For **Regions & nodes**, add "us-east1", "us-west1", and "europe-west1", with 3 nodes in each region.
   * Leave the **Hardware** and **Cluster name** as their default values.
   * For **Additional settings**, turn on VPC peering, with the default IP range.
5. Select **Next**, and on the **Summary** page, enter your credit card details.

<Note>
  You will not be charged until after your free trial expires in 30 days.
</Note>

6. Select **Create cluster**.

   Once your cluster is created, you will be redirected to the **Cluster Overview** page.
7. On the **Cluster Overview** page, select **SQL Users** from the side panel.
8. Select **Add user**, give the user a name and a password, and then add the user. You can use any user name except "root".
9. Select **Networking** from the side panel, and select **Add network**.
10. From the **Network** dropdown, select **Current Network** to auto-populate your local machine's IP address. To allow the network to access the cluster's DB Console and to use the CockroachDB client to access the databases, select the **DB Console to monitor the cluster** and **CockroachDB Client to access the databases** checkboxes.

<Note>
  After setting up your application's GCP project and GCP VPC network, you will need to return to the **Networking** page to configure VPC peering.
</Note>

### Initialize the `movr` database

1. Open a new terminal window on your local machine, and navigate to the `movr-flask` project directory.
2. In the CockroachDB Cloud Console, select **Connect** at the top-right corner of the page.
3. Select the **SQL User** that you created and the **Region** closest to you, and then select **Next**.
4. From the **Connection info** page, copy the `curl` command to download the cluster's root certificate, and execute the command in your terminal window. This root certificate is the same for all regions in a cluster.
5. From the **Connection info** page, copy the `cockroach sql` command. In the terminal window, execute the command with an `-f dbinit.sql` option at the end of the command. For example:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   $ cockroach sql --url 'postgresql://user:password@cluster.gcp-us-east1.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/root.crt' -f dbinit.sql
   ```

   This command will initialize the `movr` database on your CockroachDB Standard cluster.

## Global application deployment

To optimize the latency of requests from the application to the database, you need to deploy the application in multiple regions.

<Danger>
  This example deploys a secure web application. To take HTTPS requests, the web application must be accessible using a public domain name. SSL certificates are not assigned to IP addresses.

  We do not recommend deploying insecure web applications on public networks.
</Danger>

### Set up a GCP project

1. From the [GCP console](https://console.cloud.google.com/), create a Google Cloud project for the application.

<Note>
  Google Cloud automatically creates a `default` VPC network for each project.
</Note>

2. In the [API Library](https://console.cloud.google.com/apis/library), enable the following APIs for your project:
   * Container Registry API
   * Cloud Run Admin API
   * Serverless VPC Access API
3. **Optional:** Enable the [Google Maps Embed API](https://console.cloud.google.com/apis/library), create an API key, restrict the API key to all URLS on your domain name (e.g., `https://site.com/*`), and retrieve the API key.

<Note>
  The example HTML templates include maps. Not providing an API key to the application will prevent the maps from loading, but will not break the rest of the application.
</Note>

4. Configure/authorize the `gcloud` command-line tool to use your project and region.

<Note>
  `gcloud` is included with the [Google Cloud SDK](https://cloud.google.com/sdk) installation.
</Note>

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ gcloud init
```

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ gcloud auth login
```

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
$ gcloud auth application-default login
```

### Set up VPC peering

1. Open the CockroachDB Cloud Console for your cluster, select the **Networking**, and then select **VPC peering**.
2. Set up a new VPC peering connection, with your Google Cloud project's ID, the `default` VPC network created for your Google Cloud project, and a new VPC connection name (e.g., `movr-app-vpc`).
3. Copy the `gcloud` command provided by the console, and execute the command in a new terminal window.

<Note>
  The connection strings used to connect to CockroachDB Cloud from an application in a VPC network differ slightly from connection strings to allow-listed IP addresses.
</Note>

4. Obtain the VPC connection string for each region:
   1. Open CockroachDB Cloud Console, and select **Connect** at the top right of the page.
   2. Select **VPC Peering** for **Network Security**, your SQL username for the **SQL User**, one of the cluster regions for **Region**, `movr` for the **Database**.
   3. Select **Next**. On the following page, select the **Connection string** tab, and then copy the connection string provided.

      Take note of each region's connection string. You will need to provide connection information to the Google Cloud Run service in each region.
5. Open the Google Cloud console for your project. Under the **VPC network** services, select the **Serverless VPC access** service.
6. For each Cloud Run service, create a new VPC connector:
   * For **Name**, use a name specific to the region.
   * For **Region**, use the region of the Cloud Run service.
   * For **Network**, use `default`.
   * For **Subnet**, specify a custom IP range. This range must be an unused `/28` CIDR IP range ( `10.8.0.0`, `10.8.1.0`, `10.8.2.0`, etc.).

### Containerize the application

1. Create a new folder named `certs` at the top level of the `movr-flask` project, and then copy the root certificate that you downloaded for your cluster to the new folder. The `Dockerfile` for the application contains instructions to mount this folder and certificate onto the container.
2. Build and run the Docker image locally.

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   $ docker build -t gcr.io/<gcp_project/movr-app:v1 .
   ```

   If there are no errors, the container built successfully.
3. Push the Docker image to the Google Cloud project's container registry.

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   $ docker push gcr.io/<gcp_project/movr-app:v1
   ```

### Deploy the application

1. Create a [Google Cloud Run](https://console.cloud.google.com/run) service for the application, in one of the regions in which the database is deployed (e.g., `gcp-us-east1`):
   * Select the container image URL for the image that you just pushed to the container registry.
   * Under **Advanced settings**->**Variables & Secrets**, do the following:
     * Set an environment variable named `DB_URI` to the VPC connection string for a node on the CockroachDB Standard cluster, in the region in which this first Cloud Run service is located.

       Verify that the `DB_URI` value:

       1. Specifies `cockroachdb` as the database protocol.
       2. Includes both the username and password.
       3. Includes the path to the container-mounted root certificate (e.g., `certs/root.crt` ).

          For example: `cockroachdb://user:password@internal-cluster.gcp-us-east1.cockroachlabs.cloud:26257/movr?sslmode=verify-full&sslrootcert=certs/root.crt`
     * Set an environment variable named `REGION` to the CockroachDB Cloud region (e.g., `gcp-us-east1`).
     * **Optional:** Create a secret for your Google Maps API key and use it to set the environment variable `API_KEY`. You may need to enable the Secret Manager API to do this.
2. Repeat the Google Cloud Run set-up steps for all regions.

<Note>
  Each region has the same root certificate, but different connection strings.
</Note>

3. Create an [external HTTPS load balancer](https://console.cloud.google.com/net-services/loadbalancing) to route requests to the right service:
   * For the backend configuration, create separate network endpoint groups (NEGs) for the Google Cloud Run services in each region.
   * For the frontend configuration, make sure that you use the HTTPS protocol. You can create a [managed IP address](https://console.cloud.google.com/networking/addresses) and a [managed SSL cert](https://console.cloud.google.com/net-services/loadbalancing/advanced/sslCertificates) for the load balancer directly from the load balancer console. For the SSL cert, you will need to specify a domain name.

     For detailed instructions on setting up a load balancer for a multi-region Google Cloud Run backend, see the [GCP Load Balancer docs](https://cloud.google.com/load-balancing/docs/https/setting-up-https-serverless#ip-address).
4. In the **Cloud DNS** console (found under **Network Services**), create a new zone. You can name the zone whatever you want. Enter the same domain name for which you created a certificate earlier.
5. Select your zone, and copy the nameserver addresses (under "**Data**") for the recordset labeled "**NS**".
6. Outside of the GCP console, through your domain name provider, add the nameserver addresses to the authoritative nameserver list for your domain name.

<Note>
  It can take up to 48 hours for changes to the authoritative nameserver list to take effect.
</Note>

7. Navigate to the domain name and test out your application.

## Next steps

### Develop your own application

This tutorial demonstrates how to develop and deploy an example multi-region application. Most of the development instructions are specific to Python, Flask, and SQLAlchemy, and most of the deployment instructions are specific to Google Cloud Platform (GCP). CockroachDB supports <InternalLink path="example-apps">many more drivers and ORMs for development</InternalLink>, and you can deploy applications using a number of cloud provider orchestration tools and networking services. We encourage you to modify the code and deployments to fit your framework and use case.

### Upgrade your deployment

Some time after you have deployed your application, you will likely need to push changes that you've made locally. When pushing changes, be aware that you defined the database separate from the application. If you change a data type, for example, in your application, you will also need to modify the database schema to be compatible with your application's requests. For information about making online changes to database schemas, see <InternalLink path="online-schema-changes">Online Schema Changes</InternalLink>.

## See also

* <InternalLink version="cockroachcloud" path="quickstart">CockroachDB Cloud documentation</InternalLink>
* [Google Cloud Platform documentation](https://cloud.google.com/docs)
* [Docker documentation](https://docs.docker.com/)
* [Kubernetes documentation](https://kubernetes.io/docs/home)