App Imports: Connecting two applications

Release's App Imports functionality allows you to connect two applications with code in different repositories. You can read more about how App Imports is implemented in our microservices architecture documentation.

Here we'll show you an example of App Imports in action, using two repositories from our awesome-release directory:

• The docker-create-react-app will act as our frontend application.

• The rails_postgres_redis will act as our backend, with worker process provided by sidekiq.

Release's matching branches heuristic

Let's take a moment to understand how Release chooses which branch to use when automatically creating an environment for connected apps with different repositories.

Release will try to match a branch in the imported repository to the name of the importing repository. If there is no match, Release will fall back to either the tracking_branch or the default branch. You can also use the tracking_tag.

Here's an example to demonstrate. Say we have RepoA, RepoB, and RepoC with the following branches:

Repository	Default Branch	Tracking Branch	Other Branches
RepoA	main	main	feature-1, feature-2
RepoB	develop		feature-2
RepoC	v5	bug-1	feature-1, bug-2

• If an automatic environment request for RepoA on main is created, Release will select the develop default branch for RepoB and the bug-1 tracking branch for RepoC.

• If an automatic environment request for RepoA on feature-1 is created, Release will select the develop default branch for RepoB and the matching feature-1 branch for RepoC.

• If an automatic environment request for RepoA on feature-2 is created, Release will select the feature-2 matching branch for RepoB and the bug-1 tracking branch for RepoC.

• If an automatic environment request for RepoB or RepoC is created, the results will be similar depending on how the separate imported apps are designed. For instance, your frontend may always import the backend and a middleware proxy, but the backend will only import the proxy automatically, and not the frontend.

In our example, RepoA imports RepoB and RepoC, but it is not clear how RepoB or RepoC imports the others. If you're importing bi-directionally (or meshed, as in our three-way example), the same heuristic would apply to RepoB, RepoC, and RepoA.

Fork the repositories on Github

Navigate to the Release GitHub repository for our frontend application.

Click the Fork button in the top right corner of the page to fork the repository.

Do the same for the GitHub repository for our backend application.

You will need to grant access to the newly forked repositories. Follow the instructions in connect your source control provider to do so.

Create the backend application

The first application we'll create will be from the rails_postgres_redis repository.

When you've selected the repository, Release presents options for how the services should be run. The api service has options for both Static (because a package.json file was found) and Docker (because a Dockerfile was found). Since this is a Rails server, we'll pick Docker.

Notice that Release specifies 443 under "Public Port" for our api service. We'll use this later when we connect our two applications.

Next we'll name the application. You can give the application any name, but since this repository is the backend API for our example, we'll name it "backend".

Click the Generate App Template button to move on to the next screen.

On the Application Template screen, we don't need to make any changes, so you can go ahead and click the Save & Continue button.

We don't need to make any changes in the Build & Runtime Configurations page either, so you can click the Start Build & Deploy button to finish setting up the backend.

Create the frontend application

Now we can create an application from the docker-create-react-app repository.

Select the repository and Release will present the options for how the services will be run. This repository has only one service named app, which is configured to run in Docker, so we select Docker.

Name the app – we've named it "frontend" – then click the Generate App Template button.

This time, we'll modify the Application Template to connect our applications using the App Imports feature. Click Edit to open the Application Template.

At the bottom of the Application Template we've added:

app_imports:
- name: backend

This tells Release that when we create the frontend application, the backend application must be imported.

Click Save & Continue.

Add the environment variable

Next we need to add an environment variable to ensure the two applications can talk to each other.

Release automatically generates environment variables in the form of <SERVICE_NAME>_INGRESS_URL when the service is exposed to the internet.

When we created our backend application, we selected Docker for our api service, and Release specified that the service is exposed on public port 443. This means we'll have an environment variable in our backend named API_INGRESS_URL.

When we use App Imports to connect the applications, the ingress environment variables for backend are shared with frontend. We need to add a mapping from API_INGRESS_URL to the correct environment variable on the frontend. We'll map to the REACT_APP_BACKEND_API environment variable, which can be found in the api.js file of the repository.

If you'd like to learn more about mapping environment variables, read the section about it in our guide to environment variables.

To add the environment variable, click the Edit button in the "Default Environment Variables" section.

We added

mapping:
  REACT_APP_BACKEND_API: API_INGRESS_URL

Now our frontend application will receive the value of API_INGRESS_URL as the environment variable REACT_APP_BACKEND_API. Click Save to close the Default Environment Variables modal and click Start Build & Deploy.

View the deploy

On the App Dashboard page, we can see that a deploy is in progress.

Click on Deploy 3345 to go to the Deploy Info page where you'll see the progress.

Notice that there are four stages to this deployment: Two for the backend application and two for the frontend application. This tells us that our App Import has worked.

When deployment is complete, you can click on the Go To Environment button to view the URLs and ensure that the frontend application can talk to the backend application.

On the Environment Details page, we can see the environment for our backend application in the "Namespace" section, and the URL for our frontend application in the "Hostname URLs" section.

Click on the app link to go to the live Release environment.

View the live application

There isn't much to see when you first visit the live application, but what it's doing is making an API call to the backend to fetch users from the database and display them. Since we don't have any users yet, there are none to display.

Click on the Create New Users button to trigger a background job using Sidekiq and Redis to create users. After a short wait, the API to retrieve the users is called again and we can see that the users were successfully created.