App Imports - Connecting Two Apps Together

Overview
This is an example of taking two applications, which represent two different repositories, and connecting them together via the App Imports functionality. To read about how App Imports is implemented and the rules around using it, check out our Microservices Architecture documentation.
For this example we'll be using two repositories from our awesome-release directory. The first will be docker-create-react-app which will act as our frontend application and the second will be rails_postgres_redis which will act as our backend and worker process (via sidekiq).
Matching Branches Heuristic
When you join two application repositories in Release, how does Release decide to choose which branch to use during an automatic environment creation? Simple, Release will try to match a branch in the imported repository based on the name of the importing repository, or else it will fall back to either the tracking_branch or the default branch. (You can also use tracking_tag.) This may be a bit difficult to comprehend but a quick example will show what happens.
Let's 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 RepoB develop and RepoC bug-1 because those are the default and tracking branch, respectively.
If an automatic environment request for RepoA on feature-1 is created, Release will select RepoB develop and RepoC feature-1 because those are the default and matching heuristic branch, respectively.
If an automatic environment request for RepoA on feature-2 is created, Release will select RepoB feature-2 and RepoC bug-1 because those are the matching heuristic branch and tracking branch respectively.
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. But in our example, A imports B and C; it is not clear how B or C imports the others. You could import bi-directionally (or meshed, in our three-way example) and the same heuristic would apply to B, C and A. To offer a concrete example, you might have a frontend that always imports the backend and a middleware proxy, but the backend will always import the proxy, but may not want to import the frontend automatically.
Fork the repositories on Github
1.On Github, navigate to the repositories github.com/awesome-release/docker-create-react-app and github.com/awesome-release/rails_postgres_redis.
2.In the top-right corner of the page click Fork.
Create the applications
You will need to grant access to the newly forked repositories. Follow the instructions on Granting Repository Access to do so.
The first application we'll create will be from the rails_postgres_redis repository.
Once the repository has been selected, Release presents options on how the services will be run. The api service has options for STATIC (because a package.json) was found or DOCKER (because a Dockerfile was found). Since this is a Rails server, we'll pick docker.
The application can be named anything, but since this repository represents the backend API for our example, we're going to name it backend. Now click the GENERATE APP TEMPLATE button to move onto the next screen.
On the next screen for the Application Template, nothing needs to be changed so go ahead and click the Save & Continue button. The final screen of the application creation is Build & Runtime Configurations and we do not need to do anything on this screen either. Click Start Build & Deploy to finish setting up the backend and then we'll restart the process for the docker-create-react-app repository.
Once the repository has been selected, Release again presents options on how the services will be run. This repository only has one service, named app that will be our frontend. This repository is configured to run in Docker (was the name a give away?) so we'll again select DOCKER.
As mentioned above, this is going to be our frontend so we'll name it as such. Now click the GENERATE APP TEMPLATE button to move onto the next screen.
On the next screen for the Application Template we are going to make a change to connect our two applications together with the App Imports functionality.
At the bottom of the template we've added
1
app_imports:
2
- name: backend
Copied!
which tells Release that when we create the frontend application, we want to also import the backend application as well. We'll click SAVE & CONTINUE and move on to adding an environment variable to ensure the two applications can talk to each other.
Release auto generates environment variables in the form of <SERVICE_NAME>_INGRESS_URL when the service is exposed to the internet. Remember we selected DOCKER for our api service when we created the backend application and it was exposed on public port 443. This means we'll have an environment variable named API_INGRESS_URL. When using App Imports, the ingress environment variables for backend are shared with frontend. What we need to do is add a mapping from API_INGRESS_URL to the correct environment variable on the frontend. The environment variable we need to map to is REACT_APP_BACKEND_API which can be found in the api.js file of the repository.
If you want to read more, you can visit our Environment Variable Mapping docs.
On the next screen, click the Edit button in the Default Environment Variables section.
We added
1
mapping:
2
  REACT_APP_BACKEND_API: API_INGRESS_URL
Copied!
and 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 then the START BUILD & DEPLOY button.
View the deploy
We'll land on the App Dashboard page and can see that a Deploy is in progress. If we click on Deploy 3345 we'll be taken to the Deploy page to see the progress.
We can see that there are 4 stages to this deployment. Two are for the backend application and two are for the frontend application. This is great news! Our App Import worked and has been successfully deployed.
Click on the GO TO ENVIRONMENT button so we can view the URLs and ensure that the frontend can talk to the backend.
We can see that the environment that got created for our backend application is shown in the Namespace section and the URL for our frontend application is in the Hostname URLs section. Clicking on the app link takes us to our live Release environment.
View the live applications
There isn't much to show to start but what this application is doing is making an API call to the backend to fetch any users from the database and display them. Since we don't have any users yet, we can click on the Create New Users button to trigger a background job (utilizing Sidekiq and Redis) to create them. After a short wait, the API to retrieve the users is called again.
We can see that the users were successfully created and our apps are able to talk to each other!
Conclusion
In this example we built two applications that leveraged the App Import feature that allowed them to communicate with each other. We also implemented an Environment Variable Mapping and saw how Release is able to deploy both applications in a single Deploy object. We hope you're able to use this approach to connect your applications! Happy Releasing!