Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/uffizzicloud/backstage-ephemeral-environments

Backstage with ephemeral environments enabled
https://github.com/uffizzicloud/backstage-ephemeral-environments

Last synced: 13 days ago
JSON representation

Backstage with ephemeral environments enabled

Awesome Lists containing this project

README 

        
   

  

    Uffizzi

  

  

    Backstage

  





 Uffizzi Ephemeral Environments for Backstage





This repo provides the skeleton to get you started with using Uffizzi to create ephemeral environments for Backstage developemt. To better understand the whole system check out our blog on Backstage development here. Follow the steps below to try out the previews for Backstage and better understand how the previews are build.




## Try out Uffizzi



1. Fork the repo

2. Create a small change anywhere in the repo

3. Create a pull requests with the change commit against the fork to trigger the Github action workflows to create and Uffizzi ephemeral environment from the pull request !



The following section provides information on how the ephemeral environments work.



## Ephemeral environment builds for Backstage



### Repository structure



The `uffizzi-backstage` folder was generated by runnning the following command :



```bash

npx @backstage/create-app@latest

```



The above command also runs `yarn install` after generating the files for the backstage instance. You can go in the folder and run `yarn dev` to test the backstage instance locally.  



The folder also contains a `docker-compose.yml` which can be used for local development using docker-compose. A similar file `docker-compose.uffizzi.yml` is the earlier docker-compose with Uffizzi configuration, plus a few other edits for the configuration to work with Uffizzi. These files were added by the Uffizzi team. We will discuss this in detail in the further sections. 



> Note: To use the `docker-compose.yml` and develop locally, run the `yarn build:backend` command before running `docker-compose up`.



### Application architecture 



The following is the architecutre of the Backstage application we will be building and previewing in Uffizzi in this repo. 



![alt text](public/backstage_arch.png?raw=true "backstage architecture in this repo")



The architecture is very straightforward here with backstage and the postgres instance it is using as the database. By default backstage comes with better-sqlite configured but to showcase the usage of multiple services working in tandem with backstage we are using a database service for backstage.



Let's look at what the Uffizzi configuration looks like and what options we need to add to make the above work in the context of an ephemeral environment. 



### The Uffizzi configuration



The `docker-compose.uffizzi.yml` in the uffizzi-backstage directory of the repo is the main configuration file for Uffizzi. It is an everyday docker-compose file with the following changes made to it :-



1. The `x-uffizzi` configuration. 



```yaml

x-uffizzi:

  ingress:

    service: backstage

    port: 7007

```



The above configuration let's the Uffizzi engine know that this docker-compose file has been configured for Uffizzi. Here we define the ingress which points to the frontend of the application. The final Uffizzi URL for the ephemeral environment is created routes requests directly to the frontend service in this case.



2. Values for the `image` parameter for the services which need to be built on every change.



The values for these are are updated to use `${BACKSTAGE_IMAGE}` placeholder instead of the local build context so that they can be replaced with the image tags from the github action builds.



3. Use of `$$UFFIZZI_URL`



In the line where we are setting the arguments to be run with the command in the backstage service, 



```bash

APP_CONFIG_app_baseUrl=$$UFFIZZI_URL APP_CONFIG_backend_baseUrl=$$UFFIZZI_URL APP_CONFIG_auth_environment='production' node packages/backend --config app-config.yaml

```



we are setting the application and the backend URLs to have the same value as the `UFFIZZI_URL` environment variable. This let's backstage instance know where to query the backend from. We aren't hosting a different service for the backend so in this case the value for the backend URL and the app URL will stay the same.



The `APP_CONFIG_auth_environment` environment variable helps backstage understand which configuration to use. We are setting this to production. We will see the important parts of that configuration in the next section.



###  Backstage configuration for Uffizzi



The ephemeral environments created for backstage will be running in production mode. Hence, backstage will be looking for the `app-config.production.yaml` configuration during runtimme. We have populated this configuration file to support Uffizzi and with other integrations which would be nice to have during testing the backstage instance. Let's look at Uffizzi specific details in the configuraion:



```yaml

app:

  title: Backstage Uffizzi Environment

  baseUrl: ${UFFIZZI_URL}



backend:

  baseUrl: ${UFFIZZI_URL}

```



The above two sections; the `app` and `backend` sections of the configuration require the baseUrl to be configured. We are setting this baseUrl to be the url of the ephemeral environment created. We can get this value from the `UFFIZZI_URL` environment variable from within the ephemeral environment created. 



## Next steps



To learn more above creating epehemral environments for Backstage applications, check out our blog here and if you have any issues setting up Uffizzi or configuring Backstage, follow the links below.



Visit [docs.uffizzi.com](https://docs.uffizzi.com) for more information on epehemeral environments.

Visit [backstage.io](https://backstage.io) for further guides on Backstage development.