# Set Up a Virtual Environment for Developing Multi-Region Applications

This page walks you through setting up a virtual environment for developing and debugging an example multi-region application. It is the third section of the Develop and Deploy a Multi-Region Web Application tutorial. In this section, you will set up a demo CockroachDB cluster, initialize the database, and set up a virtual development environment.

Note:

CockroachDB versions v21.1 and above support new multi-region capabilities, with different SQL syntax.

For the latest version of the application and database schema built on v21.1 multi-region features, see the `movr-flask` repository.

For the latest version of the tutorial, see the v21.1 docs.

## Before you begin

1. Complete the previous section of the tutorial, Create a Multi-Region Database Schema.

2. Make sure that you have the following installed on your local machine:

   - CockroachDB
   - Python 3
   - Pipenv

3. Clone the `movr-flask` repository. We'll reference the source code in this repository throughout the tutorial.

## Set up a demo multi-region CockroachDB cluster

For debugging and development purposes, you can use the `cockroach demo` command. This command starts up an insecure, nine-node demo cluster.

1. To set up the demo multi-region cluster, run `cockroach demo`, with the `--nodes` and `--demo-locality` flags. The localities specified below assume GCP region names.

       $ cockroach demo \
       --nodes=9 \
       --demo-locality=region=gcp-us-east1:region=gcp-us-east1:region=gcp-us-east1:\
       region=gcp-us-west1:region=gcp-us-west1:region=gcp-us-west1:\
       region=gcp-europe-west1:region=gcp-europe-west1:region=gcp-europe-west1

       root@127.0.0.1:62268/movr>

   Note:

   Your port number will likely be different than the one shown here.

   Keep this terminal window open. Closing it will shut down the demo cluster.

2. Copy the connection string at the prompt (e.g., `root@127.0.0.1:62268/movr`).

3. Open another terminal window. In the new window, run the following command to load `dbinit.sql` to the demo database. This file contains the `movr` database definition, and SQL instructions to geo-partition the database.

       $ cockroach sql --insecure --url='postgresql://root@127.0.0.1:62268/movr' < dbinit.sql

4. In the demo cluster terminal, verify that the database schema loaded properly:

       > SHOW TABLES;

         table_name
       +------------+
         rides
         users
         vehicles
       (3 rows)

Note:

In production, you want to start a secure CockroachDB cluster, with nodes on machines located in different areas of the world. For instructions on deploying a multi-region CockroachDB cluster for this application, using CockroachCloud, see Deploy a Multi-Region Web Application.

## Set up a virtual development environment

For debugging, use `pipenv`, a tool that manages dependencies with `pip` and creates virtual environments with `virtualenv`.

1. Run the following command to initialize the project's virtual environment:

       $ pipenv --three

   `pipenv` creates a `Pipfile` in the current directory, with the requirements needed for the app.

2. Run the following command to install the packages listed in the `Pipfile`:

       $ pipenv install

3. To connect to a SQL database (like CockroachDB) from a client, you need a SQL connection string. Rather than hard-coding the connection string into the source code, the application reads it from an environment variable. Pipenv automatically sets any variables defined in a `.env` file as environment variables in a Pipenv virtual environment.

   Open `.env` and edit the `DB_URI` environment variable so that it matches the connection string for the demo cluster that you started earlier (you may need to change the `<port>`). Note that SQLAlchemy requires the connection string protocol to be specific to the CockroachDB dialect, as shown below:

       DB_URI = 'cockroachdb://root@127.0.0.1:62268/movr'

   `.env` also specifies a few other variables, like API keys and secret keys, that are used by the application. For debugging purposes, you should leave these variables as they are.

4. Activate the virtual environment:

       $ pipenv shell

   From this shell, you can run any Python 3 application with the required dependencies that you listed in the `Pipfile`, and the environment variables that you listed in the `.env` file. You can exit the shell subprocess at any time with a simple `exit` command.

5. To test out the application, you can run the server file:

       $ python server.py

6. Navigate to the URL provided to test out the application. By default, this should be http://127.0.0.1:5000/.

Note:

In production, you want to containerize your application and deploy it with a deployment orchestration tool, like Kubernetes. For instructions on deploying this application in multiple regions, see Deploy a Multi-Region Web Application.

## Next steps

Now that you've set up a development environment, you can start developing and debugging the application.

## See also

- `movr-flask` on GitHub
- `cockroach demo`
- Pipenv