Build and Deploy a gRPC-Web App Using Rust Tonic and React
14 minIntroduction
gRPC is a modern, high performance remote procedure call (RPC) framework that can be run in any environment. Built on protocol buffers (commonly called protobufs), gRPC is extensible and, efficient, and has wide support in many languages and runtimes. You can take a look at our what is gRPC post to learn more.
In this tutorial, we will go over how to deploy a React application backed by a Rust-based gRPC API to Koyeb. The demo application is a movie database website that feature showcases a selection of movies and their associated metadata. You can find the source for the two application components here:
Prerequisites
In order to follow along with this tutorial, you need the following:
- A Koyeb account to deploy the Rust and React services to. Koyeb's free tier allows you to run two services every month for free.
- The protobuf compiler installed on your local computer. We will use this to generate the language-specific stubs from our data format.
- Rust and
cargo
installed on your local computer to create the gRPC API service. - Node.js and
npm
installed on your local computer to create the React-based frontend.
Once you have satisfied the requirements, continue on to get started.
Create the Rust API
We will start by creating the Rust API for the backend and the protobuf file that defines the data format both of our services will use to communicate.
Create a new Rust project and install the dependencies
Start by defining a new Rust project.
Use the cargo
command to generate a new project directory initialized with the expected package files:
Next, move into the new project directory and install the project's dependencies:
By default, web browsers do not support gRPC, but we will use gRPC-web to make it possible.
Define the data format
Next, create the data format by creating a protobuf definition file.
Create a new directory called proto
:
Inside, create a new file named proto/movie.proto
with the following contents:
The proto/movie.proto
file defines our data format using the protobuf format. It specifies a data structure to hold all of the data about a movie and outlines what a request and response for that data will look like. This definition will be used to define the API between our services.
Create the backend service
Now that we have our data format, we can create our backend service.
Start by configuring the Rust build process to compile the protobuf file. Create a file called build.rs
with the following content:
Now we can implement the actual API server with the GetMovies
endpoint. Open the src/main.rs
file and replace the contents with the following:
The application uses the tonic gRPC implementation to build and serve the API for our backend based on the structures and interfaces defined by the protobuf file. In a real world scenario, this would typically be backed by a database containing the movie data, but to simplify the implementation, we just include data for a few movies inline.
The service will run on port 50051 by default (modifiable with the PORT
environment variable) and will respond for requests for movies using with response objects as defined by the protobuf file.
Test the API backend
The API backend is now complete, so we can start the server locally to test its functionality by typing:
The API server will be built and start running on port 50051. You can test the functionality using a gRPC client of your choice like grpcurl
or Postman.
For example, you can request the list of movies using grpcurl
by typing the following in your project's root directory with the Rust service running:
The service should return the list of movies as expected:
Create a Dockerfile
When we deploy the backend to Koyeb, the application will be run in a container. We can define a Dockerfile
for our project to describe how the project's code should be packaged and run.
In the project's root directory, create a new file called Dockerfile
with the following content:
When you are finished, add all of the files for the API to a new GitHub repository so that we can deploy it to production later.
We are ready now to create the react application that will consume the API.
Create the React application
Now that the backend is complete, we can begin working on the React frontend service for our application.
Generate a new React project
The fastest way to create a basic react application is with the create-react-app
. Check to make sure you are not in the Rust service's directory and then type:
This will a new project directory for your frontend and generate some basic files to help you get started.
Move into the new directory and start the service to validate that everything installed correctly:
A development server will open on port 3000 and React will attempt to open a new browser window to view it. You can visit localhost:3000
if you are not automatically directed there. The default React development page should appear:
Press Ctrl-c when you are finished to stop the development server.
Configure the Tailwind CSS framework
Our react application will show a list of movies on a page. To speed up the process of styling it, we are going to use Tailwind CSS. Install the necessary packages and initialize Tailwind by typing:
Now that Tailwind is installed, we need to configure the React application to support it.
First, open the tailwind.config.js
file. Modify the content
property to pick up all of our expected CSS content:
We will be using Sass instead of CSS directly, so we need to install the sass
package next:
Remove the src/App.css
file and replace it with an src/App.scss
. Inside, we import all of the Tailwind code that we require:
We can test Tailwind by changing the main React application file. Change the contents of the src/App.js
file like this:
Here, we create an application that will serve our movie list when the page is requested. At this point, we just mock up a single movie so that we can test our CSS styling.
Create a src/Movie.js
file to define how the movie should be styled and displayed:
If you start up the development server again, you should be able to see the movie mocked out:
Fetch movie lists from the API
Next, instead of displaying a hardcoded movie, we will modify the application to fetch data from the gRPC API.
First, install protobuf and gRPC web support for React:
Next, we need to generate the movie entity in JavaScript based on the same protobuf file we defined for the backend Rust application. To do this, we will use the protoc
command included in the protobuf installation from the prerequisites.
Assuming the movies-back
and movies-front
are located next to each other, you can generate the appropriate JavaScript files with the protobuf definition by running the following command in the movies-front
directory:
This will generate the appropriate JavaScript stubs from your protobuf file so that the React application understands how to communicate with the API.
Now we can change the src/App.js
file to use gRPC instead of serving a hardcoded movie:
Start the development server again to test the new changes:
This time, you should see the full movie list as served from the API backend:
After confirming that the application works as expected, add the React app's files to a new GitHub repository and push them. We will deploy the application to production in the next stage.
Deploy the application to Koyeb
Now that our frontend and backend are working as expected, we can deploy both services to Koyeb.
Deploy the API service
First, we will deploy the Rust application to Koyeb.
On the Overview tab of the Koyeb control panel, click the Create Web Service button to get started:
- Select GitHub as your deployment method.
- Select the repository for the backend API from your repository list. Alternatively, you can use the example repo for this service which contains the same code we've discussed by putting
https://github.com/filhodanuvem/movies-rust-grpc
in the Public GitHub repository field. - In the Builder section, choose Dockerfile.
- In the Exposed ports section, change the port value to 50051 and select HTTP/2 from the protocol list. Set the path to
/api
. - Click Deploy.
On the API's service page, copy the value of the Public URL. We will need this value when configuring our React application.
Deploy the React application
Now that the API is running we can deploy the React application. Unlike the API, we will use the buildpack builder for this project rather than building from a Dockerfile.
In the Apps tab of the Koyeb control panel, click on the application that includes the API service you just deployed. From the service's index page, click the Create Service button to deploy an additional service within the context of the same Koyeb App:
- Select GitHub as the deployment method.
- Select the repository for the frontend React application from your repository list. Alternatively, you can use the example repo for this service which contains the same code we've discussed by putting
https://github.com/filhodanuvem/movies-react
in the Public GitHub repository field. - In the Environment variables section, click the Add variable button and create a new variable called
REACT_APP_BACKEND_URL
. Use the API service's public URL that you copied as the value. It should look something like the following:REACT_APP_BACKEND_URL=https://<YOUR_APP_NAME>-<KOYEB_ORG_NAME>.koyeb.app/api
. - Click Deploy.
Conclusion
In this guide, we created and deployed an end-to-end application composed of a Rust backend and a React frontend. The two services communicate using gRPC. We deployed both services to Koyeb to take advantage of its native gRPC support. The services are able to communicate securely in order to fulfill user requests for the movie database site.
If you have any questions or suggestions, feel free to reach out on our community Slack.