update docs to match new build script + fixes

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
2022-11-15 11:04:19 +01:00
parent 657b0da3c7
commit 5e7bdb0109
15 changed files with 36 additions and 61 deletions
@@ -40,7 +40,7 @@ image](https://backstage.io/docs/getting-started/deployment-docker)
 documentation to build a new Backstage Docker image:

 ```shell
-$ yarn build
+$ yarn build:backend
 $ yarn build-image --tag backstage
 ```

@@ -24,7 +24,7 @@ necessary environment variables:

 ```sh
 yarn tsc
-yarn build
+yarn build:backend
 yarn workspace example-backend build-image
 docker run -p 7007:7007 example-backend
 ```
@@ -34,8 +34,8 @@ more efficient caching of dependencies on the host, where a single change won't
 bust the entire cache.

 The required steps in the host build are to install dependencies with
-`yarn install`, generate type definitions using `yarn tsc`, and build all
-packages with `yarn build`.
+`yarn install`, generate type definitions using `yarn tsc`, and build the backend
+package with `yarn build:backend`.

 > NOTE: If you created your app prior to 2021-02-18, follow the
 > [migration step](https://github.com/backstage/backstage/releases/tag/release-2021-02-18)
@@ -49,8 +49,8 @@ yarn install --frozen-lockfile
 # tsc outputs type definitions to dist-types/ in the repo root, which are then consumed by the build
 yarn tsc

-# Build all packages and in the end bundle them all up into the packages/backend/dist folder.
-yarn build
+# Build the backend, which bundles it all up into the packages/backend/dist folder.
+yarn build:backend
 ```

 Once the host build is complete, we are ready to build our image. The following
@@ -101,7 +101,8 @@ yarn workspace @backstage/plugin-api-docs start # Serve api-docs plugin only, al
 yarn tsc # Run typecheck, use --watch for watch mode
 yarn tsc:full # Run full type checking, for example without skipLibCheck, use in CI

-yarn build # Build published versions of packages, depends on tsc
+yarn build:backend # Build the backend package, depends on tsc
+yarn build:all # Build published versions of packages, depends on tsc

 yarn lint # lint packages that have changed since later commit on origin/master
 yarn lint:all # lint all packages
@@ -41,47 +41,38 @@ locally to use features like Software Templates and TechDocs. Please refer to
 the
 [installation instructions for Docker](https://docs.docker.com/engine/install/).

-## Clone and Build
+## Clone and Install

 To get up and running with a local Backstage to evaluate it, let's clone it off
-of GitHub and run an initial build.
+of GitHub and run an initial install.

 ```bash
 # Start from your local development folder
 git clone --depth 1 git@github.com:backstage/backstage.git
 cd backstage

-# Fetch our dependencies and run an initial build
+# Install our dependencies
 yarn install
-yarn tsc
-yarn build
 ```

 Phew! Now you have a local repository that's ready to run and to add any open
 source contributions into.

 We are now going to launch two things: an example Backstage frontend app, and an
-example Backstage backend that the frontend talks to. You are going to need two
-terminal windows, both starting from the Backstage project root.
-
-In the first window, run
+example Backstage backend that the frontend talks to. These can both be launched
+through the following command:

 ```bash
-# From your Backstage root directory
-yarn --cwd packages/backend start
+# From your Backstage root directory, launches both the frontend and backend
+yarn dev
 ```

-That starts up a backend instance on port 7007.
+If you prefer to run the frontend and backend separately, you can instead use `yarn start`
+and `yarn start-backend` in two separate terminal windows.

-In the other window, we will then launch the frontend. This command is run from
-the project root, not inside the backend directory.
-
-```bash
-yarn start
-```
-
-That starts up the frontend on port 3000, and should automatically open a
-browser window showing it.
+Which ever way you choose, you will now have a backend instance running on port 7007,
+and the frontend running on port 3000. A browser window should also automatically open,
+showing the frontend.

 ## Authentication

@@ -116,7 +116,7 @@ The way to execute this step of the migration is not as well defined as the prev
 - In places where the entire repo is being built, use `yarn backstage-cli repo build`, which also supports the `--since` flag. The migration here is a bit more nuanced as it depends on why you are building all packages.
  - If you are building all packages to **verify** that you are able to build them, you most likely want `backstage-cli repo build --all`. The `--all` flag signals that bundled packages like `packages/app` and `packages/backend` should be built as well. Pair this up with a `--since` flag in CI to avoid needing to build all packages.
  - If you are building all packages to **publish** them, then `backstage-cli repo build` is enough, as it builds all published packages.
-  - If you are building all packages to **deploy** them, you likely don't want to use the `repo` command at all, simply call `yarn build` in the packages you want to deploy instead. For example, if you are deploying the backend with a docker host build, it's enough to call `yarn build` inside `packages/backend`.
+  - If you are building all packages to **deploy** them, you likely don't want to use the `repo` command at all, simply call `yarn build` in the packages you want to deploy instead. For example, if you are deploying the backend with a docker host build, it's enough to call `yarn build` inside `packages/backend`. In a standard `@backstage/create-app` there is also a shorthand for building the backend from the root, `yarn build:backend`.

 ## FAQ

@@ -91,8 +91,8 @@
      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

-      To begin the development, run `npm start` or `yarn start`.
-      To create a production bundle, use `npm run build` or `yarn build`.
+      To begin the development, run `yarn start`.
+      To create a production bundle, use `yarn build`.
    -->
  </body>
 </html>
@@ -5,7 +5,7 @@
 #
 # yarn install
 # yarn tsc
-# yarn build
+# yarn build:backend
 #
 # Once the commands have been run, you can build the image using `yarn build-image`

@@ -14,8 +14,6 @@ To run the example backend, first go to the project root and run

 ```bash
 yarn install
-yarn tsc
-yarn build
 ```

 You should only need to do this once.
@@ -23,19 +21,11 @@ You should only need to do this once.
 After that, go to the `packages/backend` directory and run

 ```bash
-AUTH_GOOGLE_CLIENT_ID=x AUTH_GOOGLE_CLIENT_SECRET=x \
-AUTH_GITHUB_CLIENT_ID=x AUTH_GITHUB_CLIENT_SECRET=x \
-AUTH_OAUTH2_CLIENT_ID=x AUTH_OAUTH2_CLIENT_SECRET=x \
-AUTH_OAUTH2_AUTH_URL=x AUTH_OAUTH2_TOKEN_URL=x \
-ROLLBAR_ACCOUNT_TOKEN=x \
-SENTRY_TOKEN=x \
-LOG_LEVEL=debug \
 yarn start
 ```

-Substitute `x` for actual values, or leave them as
-dummy values just to try out the backend without using the auth or sentry features.
-You can also, instead of using dummy values for a huge number of environment variables, remove those config directly from app-config.yaml file located in the root folder.
+If you want to override any configuration locally, for example adding any secrets,
+you can do so in `app-config.local.yaml`.

 The backend starts up on port 7007 per default.

@@ -20,8 +20,8 @@
      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

-      To begin the development, run `npm start` or `yarn start`.
-      To create a production bundle, use `npm run build` or `yarn build`.
+      To begin the development, run `yarn start`.
+      To create a production bundle, use `yarn build`.
    -->
  </body>
 </html>
@@ -54,8 +54,8 @@
      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

-      To begin the development, run `npm start` or `yarn start`.
-      To create a production bundle, use `npm run build` or `yarn build`.
+      To begin the development, run `yarn start`.
+      To create a production bundle, use `yarn build`.
    -->
  </body>
 </html>
@@ -5,7 +5,7 @@
 #
 # yarn install
 # yarn tsc
-# yarn build
+# yarn build:backend
 #
 # Once the commands have been run, you can build the image using `yarn build-image`

@@ -16,8 +16,6 @@ To run the example backend, first go to the project root and run

 ```bash
 yarn install
-yarn tsc
-yarn build
 ```

 You should only need to do this once.
@@ -25,16 +23,11 @@ You should only need to do this once.
 After that, go to the `packages/backend` directory and run

 ```bash
-AUTH_GOOGLE_CLIENT_ID=x AUTH_GOOGLE_CLIENT_SECRET=x \
-AUTH_GITHUB_CLIENT_ID=x AUTH_GITHUB_CLIENT_SECRET=x \
-AUTH_OAUTH2_CLIENT_ID=x AUTH_OAUTH2_CLIENT_SECRET=x \
-AUTH_OAUTH2_AUTH_URL=x AUTH_OAUTH2_TOKEN_URL=x \
-LOG_LEVEL=debug \
 yarn start
 ```

-Substitute `x` for actual values, or leave them as dummy values just to try out
-the backend without using the auth or sentry features.
+If you want to override any configuration locally, for example adding any secrets,
+you can do so in `app-config.local.yaml`.

 The backend starts up on port 7007 per default.

@@ -11,7 +11,7 @@ All packages need to be installed and built before running the test. In a fresh
 ```sh
 yarn install
 yarn tsc
-yarn build
+yarn build:all
 ```

 Once those tasks have completed, you can now run the test using `yarn e2e-test run`.
@@ -54,8 +54,8 @@
      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

-      To begin the development, run `npm start` or `yarn start`.
-      To create a production bundle, use `npm run build` or `yarn build`.
+      To begin the development, run `yarn start`.
+      To create a production bundle, use `yarn build`.
    -->
  </body>
 </html>