Backstage_setup.playbook.md

Playbook: Setting Up Backstage Project with ngrok for Frontend and Backend

Overview

This playbook outlines the steps to set up a fresh Backstage project with ngrok for both the frontend and backend, along with configuring the app-config.yml file to ensure proper communication between the frontend and backend.

Procedure

1. Setup and Run ngrok for Frontend

• Install ngrok globally via sudo apt-get install ngrok.

• Run the following command to expose the frontend port 3000 using ngrok:

  ngrok http --host-header="localhost:3000" 3000

• Give the Frontend ngrok URL to the user.

2. Run ngrok for the Backend

• Open a new terminal window.

• Run the following command to expose the backend port 7007 using ngrok:

  ngrok http --host-header="localhost:7007" 7007

• Give the Backend ngrok URL to the user.

3. Create a Fresh Backstage Repository

• Run the following command to create a new Backstage project:

  npx @backstage/create-app@latest

4. Configure app-config.yaml with editor

• Use the following yaml code to configure the app-config.yml file:

  app:
  title: Scaffolded Backstage App
  baseUrl: http://localhost:3000
  
  organization:
    name: My Company
  
  backend:
    baseUrl: <ngrok-backend-url>
    listen:
      port: 7007
  
    csp:
      connect-src: ["'self'", 'http:', 'https:', 'ws:', 'wss:']
    cors:
      origin: ['http://localhost:3000', '<ngrok-frontend-url>']
      methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
      credentials: true
      database:
      client: better-sqlite3
      connection: ':memory:'
  
    auth:
      providers:
      guest: {}
    
    catalog:
      import:
        entityFilename: catalog-info.yaml
        pullRequestBranchName: backstage-integration
      rules:
        - allow: [Component, System, API, Resource, Location]
      locations:
        - type: file
          target: ../../examples/entities.yaml
  
        - type: file
          target: ../../examples/template/template.yaml
          rules:
            - allow: [Template]
  
        - type: file
          target: ../../examples/org.yaml
          rules:
            - allow: [User, Group]

5. Start the Project

• Run yarn dev to start the Backstage project.
• Go to http://localhost:3000/catalog on the browser to check if it's working.
• Always use localhost:3000 for frontend connections testing.

6. Readme for User

• Update the README.md file with the following steps:
  • Instructions to run ngrok for frontend and backend.
  • Details on configuring app-config.yml.
  • Any other necessary steps or changes needed by the user.

Advice and Pointers

• Always use localhost:3000 for frontend connections on the browser.
• Do not restart ngrok tunnels after the initial setup.
• Do not update or create any other files in the Backstage project that are not mentioned in this playbook.
• Do not push anything on Git Hub.
• Keep the app-config.yml file updated with the correct ngrok URLs.
• Do not create an app-config.local.yml file as it may cause conflicts with the ngrok URLs.