From abe9aab7f95b779dacfeba6ee96ef69c7afca177 Mon Sep 17 00:00:00 2001
From: Adam Laiacano <adam.laiacano@gmail.com>
Date: Sat, 21 Mar 2020 20:43:55 -0400
Subject: [PATCH 01/23] add heroku deployment steps

---
 Dockerfile            | 7 +++++++
 default.conf.template | 8 ++++++++
 2 files changed, 15 insertions(+)
 create mode 100644 default.conf.template

diff --git a/Dockerfile b/Dockerfile
index 39d51a35f2..3220e46f5f 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -15,3 +15,10 @@ RUN yarn build
 FROM nginx:mainline
 
 COPY --from=builder /app/packages/app/build /usr/share/nginx/html
+
+# Run nginx as root
+RUN sed -i 's/user  nginx.*$//' /etc/nginx/nginx.conf
+
+# Copy in the nginx conf template and replace "$PORT" with the environment variable set by heroku
+COPY default.conf.template /etc/nginx/conf.d/default.conf.template
+CMD /bin/bash -c "envsubst '\$PORT' < /etc/nginx/conf.d/default.conf.template > /etc/nginx/conf.d/default.conf" && nginx -g 'daemon off;'
diff --git a/default.conf.template b/default.conf.template
new file mode 100644
index 0000000000..9d9ff7f3e2
--- /dev/null
+++ b/default.conf.template
@@ -0,0 +1,8 @@
+server {
+  listen $PORT default_server;
+
+  location / {
+    root   /usr/share/nginx/html;
+    index  index.html;
+  }
+}
\ No newline at end of file

From e3843a90ced50b504e43bdc73c2ee2dca28e0d8f Mon Sep 17 00:00:00 2001
From: Vern Burton <me@vernburton.com>
Date: Sun, 22 Mar 2020 21:28:58 -0500
Subject: [PATCH 02/23] Creating docker-compose.yml with nginx config via a new
 site.

---
 docker-compose.yml    | 21 +++++++++++++++++++++
 docker/backstage.conf |  9 +++++++++
 2 files changed, 30 insertions(+)
 create mode 100644 docker-compose.yml
 create mode 100644 docker/backstage.conf

diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000000..90c2e6d395
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,21 @@
+version: '3.7'
+services:
+  app:
+    volumes:
+      - app_dir:/app/packages/app/build
+    build: .
+
+  web:
+    ports:
+      - 8080:80
+    volumes:
+      - ./docker/backstage.conf:/etc/nginx/conf.d/backstage.conf
+      - type: volume
+        source: app_dir
+        target: /usr/share/backstage/html
+        volume:
+          nocopy: true
+    image: nginx:mainline
+
+volumes:
+  app_dir:
\ No newline at end of file
diff --git a/docker/backstage.conf b/docker/backstage.conf
new file mode 100644
index 0000000000..b309ab0b01
--- /dev/null
+++ b/docker/backstage.conf
@@ -0,0 +1,9 @@
+server {
+   listen 80 default_server;
+   root /usr/share/backstage/html;
+   server_name backstage.local;
+   index index.html index.htm;
+   location / {
+       try_files $uri /index.html;
+   }
+}
\ No newline at end of file

From 250277a861dcd2d33977567c836384fdb676f8e4 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Tue, 24 Mar 2020 12:53:42 +0100
Subject: [PATCH 03/23] packages: mark core and cli as public

---
 packages/cli/package.json  | 3 +++
 packages/core/package.json | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index 9cc9ee6aa7..95ea0f4867 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -11,6 +11,9 @@
     "test": "backstage-cli test",
     "start": "nodemon ."
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "devDependencies": {
     "@types/fs-extra": "^8.1.0",
     "@types/html-webpack-plugin": "^3.2.2",
diff --git a/packages/core/package.json b/packages/core/package.json
index 05ee131bc9..5a967bc84c 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -12,6 +12,9 @@
     "storybook": "start-storybook -p 6006",
     "build-storybook": "build-storybook"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "@material-ui/core": "^4.9.1",
     "@material-ui/icons": "^4.9.1",

From 81ca63fd403d531f6b48067711721c9973b17f59 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Tue, 24 Mar 2020 22:04:48 +0100
Subject: [PATCH 04/23] workflows: add master build with publish

---
 .github/workflows/master.yml | 55 ++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 .github/workflows/master.yml

diff --git a/.github/workflows/master.yml b/.github/workflows/master.yml
new file mode 100644
index 0000000000..408c2594e7
--- /dev/null
+++ b/.github/workflows/master.yml
@@ -0,0 +1,55 @@
+name: Master Build
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [12.x]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: find location of yarn cache
+        id: yarn-cache
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - uses: actions/cache@v1
+        with:
+          path: ${{ steps.yarn-cache.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+      - name: cache node_modules
+        uses: actions/cache@v1
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-modules-${{ hashFiles('yarn.lock') }}
+      - name: use node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: https://registry.npmjs.org/ # Needed for auth
+      - name: yarn install, build, and test
+        run: |
+          yarn install
+          yarn lint
+          yarn build
+          yarn test
+        env:
+          CI: true
+      # Publishes current version of packages that are not already present in the registry
+      - name: publish
+        run: npx --no-install lerna publish from-package --yes
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          CI: true
+      # Tags the commit with the version in the core package if the tag doesn't exist
+      - uses: Klemensas/action-autotag@1.2.3
+        with:
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+          package_root: "packages/core"
+          tag_prefix: "v"

From 9b8d15606e287a6cccf72163e72ee22a8b3f1653 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Tue, 24 Mar 2020 22:29:47 +0100
Subject: [PATCH 05/23] packages: make plugins private for now

---
 packages/cli/templates/default-plugin/package.json.hbs | 2 +-
 plugins/home-page/package.json                         | 1 +
 plugins/welcome/package.json                           | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/cli/templates/default-plugin/package.json.hbs b/packages/cli/templates/default-plugin/package.json.hbs
index 20b78a268b..d8a303184c 100644
--- a/packages/cli/templates/default-plugin/package.json.hbs
+++ b/packages/cli/templates/default-plugin/package.json.hbs
@@ -4,7 +4,7 @@
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
   "license": "Apache-2.0",
-  "private": false,
+  "private": true,
   "scripts": {
     "build": "backstage-cli plugin:build",
     "lint": "backstage-cli lint",
diff --git a/plugins/home-page/package.json b/plugins/home-page/package.json
index 5380d8d25b..5869b5fde0 100644
--- a/plugins/home-page/package.json
+++ b/plugins/home-page/package.json
@@ -3,6 +3,7 @@
   "version": "0.1.0",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
+  "private": true,
   "devDependencies": {
     "@spotify-backstage/cli": "^0.1.0",
     "@spotify-backstage/core": "^0.1.0",
diff --git a/plugins/welcome/package.json b/plugins/welcome/package.json
index 1d5f6a7373..734ba4fea6 100644
--- a/plugins/welcome/package.json
+++ b/plugins/welcome/package.json
@@ -4,7 +4,7 @@
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
   "license": "Apache-2.0",
-  "private": false,
+  "private": true,
   "scripts": {
     "build": "backstage-cli plugin:build",
     "lint": "backstage-cli lint",

From ae61369fe18c2c78147836042751cb0e56f6259b Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Tue, 24 Mar 2020 22:55:33 +0100
Subject: [PATCH 06/23] package: added root release command for creating a
 version bump commit

---
 package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/package.json b/package.json
index 75c1dd7474..4b978bc5c9 100644
--- a/package.json
+++ b/package.json
@@ -9,6 +9,7 @@
     "build": "lerna run build",
     "test": "cross-env CI=true lerna run test -- --coverage",
     "create-plugin": "backstage-cli create-plugin",
+    "release": "if [ \"$(git symbolic-ref --short HEAD)\" = master ]; then echo \"don't try to release master\"; exit 1; else lerna version --no-push; fi",
     "lint": "lerna run lint",
     "storybook": "yarn workspace @spotify-backstage/core storybook",
     "build-storybook": "yarn workspace @spotify-backstage/core build-storybook"

From 40c2d53365b16d3a638854494b6d09b51e1b5741 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Sun, 22 Mar 2020 16:08:45 +0100
Subject: [PATCH 07/23] cli: exclude templates dir from linting

---
 DEPLOYMENT.md                                 | 38 +++++++++++++++++++
 Dockerfile                                    |  7 ----
 deployment/Dockerfile.heroku                  | 24 ++++++++++++
 .../default.conf.template                     |  2 +-
 4 files changed, 63 insertions(+), 8 deletions(-)
 create mode 100644 DEPLOYMENT.md
 create mode 100644 deployment/Dockerfile.heroku
 rename default.conf.template => deployment/default.conf.template (98%)

diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
new file mode 100644
index 0000000000..47cd67e8ef
--- /dev/null
+++ b/DEPLOYMENT.md
@@ -0,0 +1,38 @@
+# Deploying Backstage
+
+## Heroku
+
+Deploying to heroku is relatively easy following these steps.
+
+First, make sure you have the [heroku CLI installed](https://devcenter.heroku.com/articles/heroku-cli) and log into it as well as loging into Heroku's [container registry](https://devcenter.heroku.com/articles/container-registry-and-runtime).
+
+```bash
+$ heroku login
+$ heroku container:login
+```
+
+You _might_ also need to set your Heroku app's stack to `container`
+
+```bash
+$ heroku stack:set container -a <your-app>
+```
+
+There are two small tweaks made to Backstage's default Dockerfile to run on Heroku:
+
+1. Do not run nginx as the `nginx` user.
+2. Replace the standard port (80) in `/etc/nginx/conf.d/default.conf` with the wildcard `$PORT`, which Heroku will set for us.
+
+These changes are in the `deployment/Dockerfile.heroku` file, which you will need to copy into your root directory before deploying:
+
+```bash
+$ cp deployment/Dockerfile.heroku Dockerfile
+```
+
+With these changes, we can build/push the Docker image to Heroku's container registry and release it to the `web` worker.
+
+```bash
+$ heroku container:push web -a <your-app>
+$ heroku container:release web -a <your-app>
+```
+
+With that, you should have Backstage up and running!
diff --git a/Dockerfile b/Dockerfile
index 3220e46f5f..39d51a35f2 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -15,10 +15,3 @@ RUN yarn build
 FROM nginx:mainline
 
 COPY --from=builder /app/packages/app/build /usr/share/nginx/html
-
-# Run nginx as root
-RUN sed -i 's/user  nginx.*$//' /etc/nginx/nginx.conf
-
-# Copy in the nginx conf template and replace "$PORT" with the environment variable set by heroku
-COPY default.conf.template /etc/nginx/conf.d/default.conf.template
-CMD /bin/bash -c "envsubst '\$PORT' < /etc/nginx/conf.d/default.conf.template > /etc/nginx/conf.d/default.conf" && nginx -g 'daemon off;'
diff --git a/deployment/Dockerfile.heroku b/deployment/Dockerfile.heroku
new file mode 100644
index 0000000000..15878c67da
--- /dev/null
+++ b/deployment/Dockerfile.heroku
@@ -0,0 +1,24 @@
+FROM node:12 as builder
+WORKDIR /app
+
+COPY package.json yarn.lock .yarnrc .npmrc /app/
+COPY .yarn /app/.yarn
+COPY packages /app/packages
+COPY plugins /app/plugins
+
+RUN yarn
+
+COPY . .
+
+RUN yarn build
+
+FROM nginx:mainline
+
+COPY --from=builder /app/packages/app/build /usr/share/nginx/html
+
+# Run nginx as root
+RUN sed -i 's/user  nginx.*$//' /etc/nginx/nginx.conf
+
+# Copy in the nginx conf template and replace "$PORT" with the environment variable set by heroku
+COPY deployment/default.conf.template /etc/nginx/conf.d/default.conf.template
+CMD /bin/bash -c "envsubst '\$PORT' < /etc/nginx/conf.d/default.conf.template > /etc/nginx/conf.d/default.conf" && nginx -g 'daemon off;'
diff --git a/default.conf.template b/deployment/default.conf.template
similarity index 98%
rename from default.conf.template
rename to deployment/default.conf.template
index 9d9ff7f3e2..61c32aa95e 100644
--- a/default.conf.template
+++ b/deployment/default.conf.template
@@ -5,4 +5,4 @@ server {
     root   /usr/share/nginx/html;
     index  index.html;
   }
-}
\ No newline at end of file
+}

From 123e5f80a8618e6df1ae0a5f99482761eb05df40 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 25 Mar 2020 01:24:49 +0100
Subject: [PATCH 08/23] package: update storybook command and remove build
 command

---
 package.json | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/package.json b/package.json
index 7c6f997efb..8a008a5ed3 100644
--- a/package.json
+++ b/package.json
@@ -10,8 +10,7 @@
     "test": "cross-env CI=true lerna run test --since origin/master -- --coverage",
     "create-plugin": "backstage-cli create-plugin",
     "lint": "lerna run lint",
-    "storybook": "yarn workspace @spotify-backstage/core storybook",
-    "build-storybook": "yarn workspace @spotify-backstage/core build-storybook"
+    "storybook": "yarn workspace storybook start"
   },
   "workspaces": {
     "packages": [

From 5012ce53353e1ff43ad8260b1590f07b3835c095 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 25 Mar 2020 11:09:53 +0100
Subject: [PATCH 09/23] github/workflows: update yarn cache step names

---
 .github/workflows/cli.yml      | 5 +++--
 .github/workflows/frontend.yml | 5 +++--
 .github/workflows/master.yml   | 5 +++--
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/cli.yml b/.github/workflows/cli.yml
index b8465d96e5..e7d8c53b90 100644
--- a/.github/workflows/cli.yml
+++ b/.github/workflows/cli.yml
@@ -17,10 +17,11 @@ jobs:
     name: Node ${{ matrix.node-version }} on ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v2
-      - name: find location of yarn cache
+      - name: find location of global yarn cache
         id: yarn-cache
         run: echo "::set-output name=dir::$(yarn cache dir)"
-      - uses: actions/cache@v1
+      - name: cache global yarn cache
+        uses: actions/cache@v1
         with:
           path: ${{ steps.yarn-cache.outputs.dir }}
           key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
diff --git a/.github/workflows/frontend.yml b/.github/workflows/frontend.yml
index 2842442bf9..be2a915b70 100644
--- a/.github/workflows/frontend.yml
+++ b/.github/workflows/frontend.yml
@@ -14,10 +14,11 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - name: find location of yarn cache
+      - name: find location of global yarn cache
         id: yarn-cache
         run: echo "::set-output name=dir::$(yarn cache dir)"
-      - uses: actions/cache@v1
+      - name: cache global yarn cache
+        uses: actions/cache@v1
         with:
           path: ${{ steps.yarn-cache.outputs.dir }}
           key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
diff --git a/.github/workflows/master.yml b/.github/workflows/master.yml
index 408c2594e7..8e82c36373 100644
--- a/.github/workflows/master.yml
+++ b/.github/workflows/master.yml
@@ -14,10 +14,11 @@ jobs:
 
     steps:
       - uses: actions/checkout@v2
-      - name: find location of yarn cache
+      - name: find location of global yarn cache
         id: yarn-cache
         run: echo "::set-output name=dir::$(yarn cache dir)"
-      - uses: actions/cache@v1
+      - name: cache global yarn cache
+        uses: actions/cache@v1
         with:
           path: ${{ steps.yarn-cache.outputs.dir }}
           key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}

From 3dd16111806f53a1d201230b1b1c4d63de3379c9 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 25 Mar 2020 11:16:18 +0100
Subject: [PATCH 10/23] workflows/master: split yarn tasks into separate steps

---
 .github/workflows/master.yml | 16 +++++++---------
 1 file changed, 7 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/master.yml b/.github/workflows/master.yml
index 8e82c36373..1985215a0e 100644
--- a/.github/workflows/master.yml
+++ b/.github/workflows/master.yml
@@ -12,6 +12,9 @@ jobs:
       matrix:
         node-version: [12.x]
 
+    env:
+      CI: true
+
     steps:
       - uses: actions/checkout@v2
       - name: find location of global yarn cache
@@ -34,20 +37,15 @@ jobs:
         with:
           node-version: ${{ matrix.node-version }}
           registry-url: https://registry.npmjs.org/ # Needed for auth
-      - name: yarn install, build, and test
-        run: |
-          yarn install
-          yarn lint
-          yarn build
-          yarn test
-        env:
-          CI: true
+      - run: yarn install
+      - run: yarn lint
+      - run: yarn build
+      - run: yarn test
       # Publishes current version of packages that are not already present in the registry
       - name: publish
         run: npx --no-install lerna publish from-package --yes
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-          CI: true
       # Tags the commit with the version in the core package if the tag doesn't exist
       - uses: Klemensas/action-autotag@1.2.3
         with:

From 59c1cba6b971822479d43086c2caa618fd70fa58 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 25 Mar 2020 12:11:17 +0100
Subject: [PATCH 11/23] docs: added npm publishing docs

---
 docs/README.md     |  1 +
 docs/publishing.md | 37 +++++++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 docs/publishing.md

diff --git a/docs/README.md b/docs/README.md
index 74e71370e1..c645b33024 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -5,3 +5,4 @@ Check out [https://backstage.io]() or see the table of content below.
 - [Architecture and terminology](architecture-terminology.md)
 - [Getting started](getting-started/README.md)
 - [References](reference/README.md)
+- [Publishing](publishing.md)
diff --git a/docs/publishing.md b/docs/publishing.md
new file mode 100644
index 0000000000..15eaadd95d
--- /dev/null
+++ b/docs/publishing.md
@@ -0,0 +1,37 @@
+# Publishing
+
+## NPM
+
+NPM packages are published through CI/CD in the
+[.github/workflows/master.yml](../.github/workflows/master.yml) workflow. Every
+commit that is merged to master will be checked for new versions of all public
+packages, and any new versions will automatically be published to NPM.
+
+### Creating a new release
+
+Version bumps are made through release PRs. To create a new release, checkout out
+a new branch that you will use for the release, e.g.
+
+```sh
+$ git checkout -b new-release
+```
+
+Then, from the root of the repo, run
+
+```sh
+$ yarn release
+```
+
+This will bring up the lerna release CLI where you choose what type of version bump
+you want to make, (major/minor/patch/prerelease). The CLI will take you through choosing
+a version, previewing all changes, and then approving the release. Once the release
+is approved, a new commit is created that you can submit as a PR. Push the branch to GitHub:
+
+```sh
+$ git push origin -u new-release
+```
+
+And then create a PR. Once the PR is approved and merged into master, the master build
+will publish new versions of all bumped packages.
+
+[Back to Docs](README.md)

From 80eeaa836bbaeaa97225a0304a736affbb0d5891 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 25 Mar 2020 12:40:14 +0100
Subject: [PATCH 12/23] workflows/frontend: split yarn tasks into separate
 steps (#383)

---
 .github/workflows/frontend.yml | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/frontend.yml b/.github/workflows/frontend.yml
index 527639abf1..fecab189e1 100644
--- a/.github/workflows/frontend.yml
+++ b/.github/workflows/frontend.yml
@@ -12,6 +12,9 @@ jobs:
       matrix:
         node-version: [12.x]
 
+    env:
+      CI: true
+
     steps:
       - uses: actions/checkout@v2
       - name: fetch branch master
@@ -34,11 +37,7 @@ jobs:
         uses: actions/setup-node@v1
         with:
           node-version: ${{ matrix.node-version }}
-      - name: yarn install, build, and test
-        run: |
-          yarn install
-          yarn lint
-          yarn build
-          yarn test
-        env:
-          CI: true
+      - run: yarn install
+      - run: yarn lint
+      - run: yarn build
+      - run: yarn test

From cf446052bc9f48f244700aac4b1a489fa7b8d42d Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 25 Mar 2020 12:57:54 +0100
Subject: [PATCH 13/23] packages: add READMEs

---
 packages/app/README.md       |  3 +++
 packages/cli/README.md       | 22 ++++++++++++++++++++++
 packages/core/README.md      | 22 ++++++++++++++++++++++
 packages/storybook/README.md |  3 +++
 4 files changed, 50 insertions(+)
 create mode 100644 packages/app/README.md
 create mode 100644 packages/cli/README.md
 create mode 100644 packages/core/README.md
 create mode 100644 packages/storybook/README.md

diff --git a/packages/app/README.md b/packages/app/README.md
new file mode 100644
index 0000000000..cabf812650
--- /dev/null
+++ b/packages/app/README.md
@@ -0,0 +1,3 @@
+# @spotify-backstage/app
+
+This package is an example of a Backstage application.
diff --git a/packages/cli/README.md b/packages/cli/README.md
new file mode 100644
index 0000000000..99afb635ce
--- /dev/null
+++ b/packages/cli/README.md
@@ -0,0 +1,22 @@
+# @backstage/cli
+
+This package provides a CLI for developing Backstage plugins and apps.
+
+## Installation
+
+Install the package via npm or yarn:
+
+```sh
+$ npm install --save @backstage/cli
+```
+
+or
+
+```sh
+$ yarn add @backstage/cli
+```
+
+## Documentation
+
+- [Backstage Readme](https://github.com/spotify/backstage/blob/master/README.md)
+- [Backstage Documentation](https://github.com/spotify/backstage/blob/master/docs/README.md)
diff --git a/packages/core/README.md b/packages/core/README.md
new file mode 100644
index 0000000000..a22f66ecd9
--- /dev/null
+++ b/packages/core/README.md
@@ -0,0 +1,22 @@
+# @backstage/core
+
+This package provides the core API used by Backstage plugins and apps.
+
+## Installation
+
+Install the package via npm or yarn:
+
+```sh
+$ npm install --save @backstage/core
+```
+
+or
+
+```sh
+$ yarn add @backstage/core
+```
+
+## Documentation
+
+- [Backstage Readme](https://github.com/spotify/backstage/blob/master/README.md)
+- [Backstage Documentation](https://github.com/spotify/backstage/blob/master/docs/README.md)
diff --git a/packages/storybook/README.md b/packages/storybook/README.md
new file mode 100644
index 0000000000..2e716a5466
--- /dev/null
+++ b/packages/storybook/README.md
@@ -0,0 +1,3 @@
+# storybook
+
+This package provides a storybook build for Backstage. See [storybook.backstage.io](http://storybook.backstage.io)

From ca992f6cc44d886a7df3ec2ce9ae81e029e019d8 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 25 Mar 2020 12:59:29 +0100
Subject: [PATCH 14/23] packages/{core,cli}: fill in missing package.json
 fields for publishing

---
 packages/cli/package.json  | 17 +++++++++++++++--
 packages/core/package.json | 15 ++++++++++++++-
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index 9cc9ee6aa7..657315d959 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,9 +1,22 @@
 {
   "name": "@spotify-backstage/cli",
+  "description": "CLI for developing Backstage plugins and apps",
   "version": "0.1.0",
-  "main": "dist",
-  "license": "Apache-2.0",
   "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spotify/backstage",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "license": "Apache-2.0",
+  "main": "dist",
   "scripts": {
     "exec": "npx ts-node ./src",
     "build": "tsc --outDir dist --noEmit false --module CommonJS",
diff --git a/packages/core/package.json b/packages/core/package.json
index b6ceeb42f2..d1fb12fdec 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,8 +1,21 @@
 {
   "name": "@spotify-backstage/core",
+  "description": "Core API used by Backstage plugins and apps",
   "version": "0.1.0",
-  "license": "Apache-2.0",
   "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spotify/backstage",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "license": "Apache-2.0",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
   "scripts": {

From 3a0d8edcb57c25ff23b3e935d5342de2b25b1641 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 25 Mar 2020 19:12:11 +0100
Subject: [PATCH 15/23] rename npm namespace from @spotify-backstage to
 @backstage

---
 .eslintrc.js                                           |  6 +++---
 docs/getting-started/Plugin development.md             |  2 +-
 docs/getting-started/structure-of-a-plugin.md          |  2 +-
 docs/reference/createPlugin.md                         |  2 +-
 package.json                                           |  2 +-
 packages/app/README.md                                 |  2 +-
 packages/app/package.json                              | 10 +++++-----
 packages/app/src/App.tsx                               |  2 +-
 packages/app/src/apis.ts                               |  2 +-
 .../app/src/components/ErrorDisplay/ErrorDisplay.tsx   |  2 +-
 packages/app/src/components/Root/Root.tsx              |  2 +-
 packages/app/src/plugins.ts                            |  4 ++--
 packages/cli/package.json                              |  2 +-
 .../src/commands/create-plugin/createPlugin.test.ts    |  5 ++---
 .../cli/src/commands/create-plugin/createPlugin.ts     |  6 +++---
 packages/cli/src/commands/watch-deps/index.ts          |  2 +-
 packages/cli/templates/default-plugin/package.json.hbs |  4 ++--
 .../ExampleComponent/ExampleComponent.test.tsx.hbs     |  2 +-
 .../ExampleComponent/ExampleComponent.tsx.hbs          |  2 +-
 .../ExampleFetchComponent.tsx.hbs                      |  2 +-
 .../cli/templates/default-plugin/src/plugin.ts.hbs     |  2 +-
 packages/core/package.json                             |  4 ++--
 plugins/home-page/package.json                         |  6 +++---
 .../src/components/HomePage/HomePage.test.tsx          |  2 +-
 plugins/home-page/src/components/HomePage/HomePage.tsx |  8 +-------
 .../src/components/HomePage/SquadTechHealth.tsx        |  2 +-
 .../src/components/HomepageTimer/HomepageTimer.tsx     |  2 +-
 plugins/home-page/src/plugin.ts                        |  2 +-
 plugins/welcome/package.json                           |  6 +++---
 plugins/welcome/src/components/Timer/Timer.tsx         |  2 +-
 .../src/components/WelcomePage/ErrorButton.test.tsx    |  2 +-
 .../welcome/src/components/WelcomePage/ErrorButton.tsx |  2 +-
 .../src/components/WelcomePage/WelcomePage.test.tsx    |  2 +-
 .../welcome/src/components/WelcomePage/WelcomePage.tsx |  2 +-
 plugins/welcome/src/plugin.ts                          |  2 +-
 35 files changed, 51 insertions(+), 58 deletions(-)

diff --git a/.eslintrc.js b/.eslintrc.js
index c227c17938..969b6d7d5e 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -1,5 +1,5 @@
-const path = require('path')
-const base = require('@spotify-backstage/cli/config/eslint');
+const path = require('path');
+const base = require('@backstage/cli/config/eslint');
 
 module.exports = {
   ...base,
@@ -8,7 +8,7 @@ module.exports = {
     'notice/notice': [
       'error',
       {
-        templateFile: path.resolve(__dirname, "scripts/copyright.js"),
+        templateFile: path.resolve(__dirname, 'scripts/copyright.js'),
       },
     ],
   },
diff --git a/docs/getting-started/Plugin development.md b/docs/getting-started/Plugin development.md
index 45cb171ef9..774a02434e 100644
--- a/docs/getting-started/Plugin development.md	
+++ b/docs/getting-started/Plugin development.md	
@@ -40,7 +40,7 @@ The app will call the `createPlugin` method on each plugin, passing in a `router
 of methods on it.
 
 ```typescript
-import { createPlugin } from '@spotify-backstage/core';
+import { createPlugin } from '@backstage/core';
 import ExampleComponent from './components/ExampleComponent';
 
 export default createPlugin({
diff --git a/docs/getting-started/structure-of-a-plugin.md b/docs/getting-started/structure-of-a-plugin.md
index c6034261f1..2b31221373 100644
--- a/docs/getting-started/structure-of-a-plugin.md
+++ b/docs/getting-started/structure-of-a-plugin.md
@@ -43,7 +43,7 @@ In the root folder you have some configuration for typescript and jest, the test
 In the `src` folder we get to the interesting bits. Check out the `plugin.ts`:
 
 ```jsx
-import { createPlugin } from '@spotify-backstage/core';
+import { createPlugin } from '@backstage/core';
 import ExampleComponent from './components/ExampleComponent';
 
 export default createPlugin({
diff --git a/docs/reference/createPlugin.md b/docs/reference/createPlugin.md
index 779e1ef820..77048199ef 100644
--- a/docs/reference/createPlugin.md
+++ b/docs/reference/createPlugin.md
@@ -26,7 +26,7 @@ type PluginHooks = {
 Showcasing adding multiple routes and a redirect.
 
 ```jsx
-import { createPlugin } from '@spotify-backstage/core';
+import { createPlugin } from '@backstage/core';
 import ExampleComponent from './components/ExampleComponent';
 
 export default createPlugin({
diff --git a/package.json b/package.json
index a25335f659..736da36ac9 100644
--- a/package.json
+++ b/package.json
@@ -5,7 +5,7 @@
     "node": ">=12.0.0"
   },
   "scripts": {
-    "start": "yarn build && yarn workspace @spotify-backstage/app start",
+    "start": "yarn build && yarn workspace @backstage/app start",
     "build": "lerna run build",
     "test": "cross-env CI=true lerna run test --since origin/master -- --coverage",
     "create-plugin": "backstage-cli create-plugin",
diff --git a/packages/app/README.md b/packages/app/README.md
index cabf812650..0e4aa9912e 100644
--- a/packages/app/README.md
+++ b/packages/app/README.md
@@ -1,3 +1,3 @@
-# @spotify-backstage/app
+# @backstage/app
 
 This package is an example of a Backstage application.
diff --git a/packages/app/package.json b/packages/app/package.json
index 4f581599a5..468e2842db 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -1,15 +1,15 @@
 {
-  "name": "@spotify-backstage/app",
+  "name": "@backstage/app",
   "version": "0.0.0",
   "private": true,
   "dependencies": {
     "@material-ui/core": "^4.9.1",
     "@material-ui/icons": "^4.9.1",
     "@material-ui/lab": "4.0.0-alpha.45",
-    "@spotify-backstage/cli": "^0.1.0",
-    "@spotify-backstage/core": "^0.1.0",
-    "@spotify-backstage/plugin-home-page": "^0.1.0",
-    "@spotify-backstage/plugin-welcome": "^0.1.0",
+    "@backstage/cli": "^0.1.0",
+    "@backstage/core": "^0.1.0",
+    "@backstage/plugin-home-page": "^0.1.0",
+    "@backstage/plugin-welcome": "^0.1.0",
     "@testing-library/jest-dom": "^4.2.4",
     "@testing-library/react": "^9.3.2",
     "@testing-library/user-event": "^7.1.2",
diff --git a/packages/app/src/App.tsx b/packages/app/src/App.tsx
index 91b588041c..09d7f55094 100644
--- a/packages/app/src/App.tsx
+++ b/packages/app/src/App.tsx
@@ -15,7 +15,7 @@
  */
 
 import { CssBaseline, makeStyles, ThemeProvider } from '@material-ui/core';
-import { BackstageTheme, createApp } from '@spotify-backstage/core';
+import { BackstageTheme, createApp } from '@backstage/core';
 import React, { FC } from 'react';
 import { BrowserRouter as Router } from 'react-router-dom';
 import Root from './components/Root';
diff --git a/packages/app/src/apis.ts b/packages/app/src/apis.ts
index 6e2de63795..c3315257d8 100644
--- a/packages/app/src/apis.ts
+++ b/packages/app/src/apis.ts
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { ApiHolder, ApiRegistry, errorApiRef } from '@spotify-backstage/core';
+import { ApiHolder, ApiRegistry, errorApiRef } from '@backstage/core';
 import { ErrorDisplayForwarder } from './components/ErrorDisplay/ErrorDisplay';
 
 const builder = ApiRegistry.builder();
diff --git a/packages/app/src/components/ErrorDisplay/ErrorDisplay.tsx b/packages/app/src/components/ErrorDisplay/ErrorDisplay.tsx
index 307158d88c..25e87c7bff 100644
--- a/packages/app/src/components/ErrorDisplay/ErrorDisplay.tsx
+++ b/packages/app/src/components/ErrorDisplay/ErrorDisplay.tsx
@@ -18,7 +18,7 @@ import React, { FC, useEffect, useState } from 'react';
 import PropTypes from 'prop-types';
 import { Snackbar } from '@material-ui/core';
 import { Alert } from '@material-ui/lab';
-import { ErrorApi, ErrorContext } from '@spotify-backstage/core';
+import { ErrorApi, ErrorContext } from '@backstage/core';
 
 type SubscriberFunc = (error: Error) => void;
 type Unsubscribe = () => void;
diff --git a/packages/app/src/components/Root/Root.tsx b/packages/app/src/components/Root/Root.tsx
index 8795b50e1d..920f5c9871 100644
--- a/packages/app/src/components/Root/Root.tsx
+++ b/packages/app/src/components/Root/Root.tsx
@@ -28,7 +28,7 @@ import {
   SidebarSpacer,
   SidebarDivider,
   SidebarSpace,
-} from '@spotify-backstage/core';
+} from '@backstage/core';
 
 const useSidebarLogoStyles = makeStyles({
   root: {
diff --git a/packages/app/src/plugins.ts b/packages/app/src/plugins.ts
index 12bba3ac06..3c757a59c9 100644
--- a/packages/app/src/plugins.ts
+++ b/packages/app/src/plugins.ts
@@ -1,3 +1,3 @@
 /* eslint-disable notice/notice */
-export { default as HomePagePlugin } from '@spotify-backstage/plugin-home-page';
-export { default as WelcomePlugin } from '@spotify-backstage/plugin-welcome';
+export { default as HomePagePlugin } from '@backstage/plugin-home-page';
+export { default as WelcomePlugin } from '@backstage/plugin-welcome';
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 1e85c44c97..bf24095c61 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@spotify-backstage/cli",
+  "name": "@backstage/cli",
   "description": "CLI for developing Backstage plugins and apps",
   "version": "0.1.0",
   "private": false,
diff --git a/packages/cli/src/commands/create-plugin/createPlugin.test.ts b/packages/cli/src/commands/create-plugin/createPlugin.test.ts
index 1d78cb9191..9bf50027e3 100644
--- a/packages/cli/src/commands/create-plugin/createPlugin.test.ts
+++ b/packages/cli/src/commands/create-plugin/createPlugin.test.ts
@@ -59,9 +59,8 @@ describe('createPlugin', () => {
       const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'test-'));
       try {
         const sourceData =
-          '{"name": "@spotify-backstage/{{id}}", "version": "{{version}}"}';
-        const targetData =
-          '{"name": "@spotify-backstage/foo", "version": "0.0.0"}';
+          '{"name": "@backstage/{{id}}", "version": "{{version}}"}';
+        const targetData = '{"name": "@backstage/foo", "version": "0.0.0"}';
         const sourcePath = path.join(tempDir, 'in.hbs');
         const targetPath = path.join(tempDir, 'out.json');
         fs.writeFileSync(sourcePath, sourceData);
diff --git a/packages/cli/src/commands/create-plugin/createPlugin.ts b/packages/cli/src/commands/create-plugin/createPlugin.ts
index 112377cbda..4d264b01f9 100644
--- a/packages/cli/src/commands/create-plugin/createPlugin.ts
+++ b/packages/cli/src/commands/create-plugin/createPlugin.ts
@@ -130,7 +130,7 @@ export const addPluginDependencyToApp = (
   console.log();
   console.log(chalk.green(' Adding plugin as dependency in app:'));
 
-  const pluginPackage = `@spotify-backstage/plugin-${pluginName}`;
+  const pluginPackage = `@backstage/plugin-${pluginName}`;
   const packageFile = path.join(rootDir, 'packages', 'app', 'package.json');
 
   process.stdout.write(
@@ -171,7 +171,7 @@ export const addPluginToApp = (rootDir: string, pluginName: string) => {
   console.log();
   console.log(chalk.green(' Import plugin in app:'));
 
-  const pluginPackage = `@spotify-backstage/plugin-${pluginName}`;
+  const pluginPackage = `@backstage/plugin-${pluginName}`;
   const pluginNameCapitalized = pluginName
     .split('-')
     .map(name => capitalize(name))
@@ -414,7 +414,7 @@ const createPlugin = async () => {
     console.log(
       chalk.green(
         `🥇  Successfully created ${chalk.cyan(
-          `@spotify-backstage/plugin-${answers.id}`,
+          `@backstage/plugin-${answers.id}`,
         )}`,
       ),
     );
diff --git a/packages/cli/src/commands/watch-deps/index.ts b/packages/cli/src/commands/watch-deps/index.ts
index e5993ae9d6..059c2a7b5e 100644
--- a/packages/cli/src/commands/watch-deps/index.ts
+++ b/packages/cli/src/commands/watch-deps/index.ts
@@ -26,7 +26,7 @@ import { waitForExit } from '../../helpers/run';
 
 const PACKAGE_BLACKLIST = [
   // We never want to watch for changes in the cli, but all packages will depend on it.
-  '@spotify-backstage/cli',
+  '@backstage/cli',
 ];
 
 const WATCH_LOCATIONS = ['package.json', 'src', 'assets'];
diff --git a/packages/cli/templates/default-plugin/package.json.hbs b/packages/cli/templates/default-plugin/package.json.hbs
index d8a303184c..6e416f3287 100644
--- a/packages/cli/templates/default-plugin/package.json.hbs
+++ b/packages/cli/templates/default-plugin/package.json.hbs
@@ -1,5 +1,5 @@
 {
-  "name": "@spotify-backstage/plugin-{{id}}",
+  "name": "@backstage/plugin-{{id}}",
   "version": "{{version}}",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
@@ -11,7 +11,7 @@
     "test": "backstage-cli test"
   },
   "devDependencies": {
-    "@spotify-backstage/cli": "^{{version}}",
+    "@backstage/cli": "^{{version}}",
     "@types/testing-library__jest-dom": "5.0.2",
     "jest-fetch-mock": "^3.0.3"
   },
diff --git a/packages/cli/templates/default-plugin/src/components/ExampleComponent/ExampleComponent.test.tsx.hbs b/packages/cli/templates/default-plugin/src/components/ExampleComponent/ExampleComponent.test.tsx.hbs
index 360055dc3d..15db0863d2 100644
--- a/packages/cli/templates/default-plugin/src/components/ExampleComponent/ExampleComponent.test.tsx.hbs
+++ b/packages/cli/templates/default-plugin/src/components/ExampleComponent/ExampleComponent.test.tsx.hbs
@@ -19,7 +19,7 @@ import { render } from '@testing-library/react';
 import mockFetch from 'jest-fetch-mock';
 import ExampleComponent from './ExampleComponent';
 import { ThemeProvider } from '@material-ui/core';
-import { BackstageTheme } from '@spotify-backstage/core';
+import { BackstageTheme } from '@backstage/core';
 
 describe('ExampleComponent', () => {
   it('should render', () => {
diff --git a/packages/cli/templates/default-plugin/src/components/ExampleComponent/ExampleComponent.tsx.hbs b/packages/cli/templates/default-plugin/src/components/ExampleComponent/ExampleComponent.tsx.hbs
index b5c56422da..b96c970022 100644
--- a/packages/cli/templates/default-plugin/src/components/ExampleComponent/ExampleComponent.tsx.hbs
+++ b/packages/cli/templates/default-plugin/src/components/ExampleComponent/ExampleComponent.tsx.hbs
@@ -25,7 +25,7 @@ import {
   ContentHeader,
   HeaderLabel,
   SupportButton,
-} from '@spotify-backstage/core';
+} from '@backstage/core';
 import ExampleFetchComponent from '../ExampleFetchComponent';
 
 const ExampleComponent: FC<{}> = () => (
diff --git a/packages/cli/templates/default-plugin/src/components/ExampleFetchComponent/ExampleFetchComponent.tsx.hbs b/packages/cli/templates/default-plugin/src/components/ExampleFetchComponent/ExampleFetchComponent.tsx.hbs
index 4801dea6dd..3420cc9d5a 100644
--- a/packages/cli/templates/default-plugin/src/components/ExampleFetchComponent/ExampleFetchComponent.tsx.hbs
+++ b/packages/cli/templates/default-plugin/src/components/ExampleFetchComponent/ExampleFetchComponent.tsx.hbs
@@ -25,7 +25,7 @@ import TableHead from '@material-ui/core/TableHead';
 import TableRow from '@material-ui/core/TableRow';
 import Alert from '@material-ui/lab/Alert';
 import { useAsync } from 'react-use';
-import { Progress } from '@spotify-backstage/core';
+import { Progress } from '@backstage/core';
 
 const useStyles = makeStyles({
   table: {
diff --git a/packages/cli/templates/default-plugin/src/plugin.ts.hbs b/packages/cli/templates/default-plugin/src/plugin.ts.hbs
index ccac096007..bb0b93ca25 100644
--- a/packages/cli/templates/default-plugin/src/plugin.ts.hbs
+++ b/packages/cli/templates/default-plugin/src/plugin.ts.hbs
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { createPlugin } from '@spotify-backstage/core';
+import { createPlugin } from '@backstage/core';
 import ExampleComponent from './components/ExampleComponent';
 
 export default createPlugin({
diff --git a/packages/core/package.json b/packages/core/package.json
index b18705316c..48bbe83cd6 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@spotify-backstage/core",
+  "name": "@backstage/core",
   "description": "Core API used by Backstage plugins and apps",
   "version": "0.1.0",
   "private": false,
@@ -42,7 +42,7 @@
     "recompose": "0.30.0"
   },
   "devDependencies": {
-    "@spotify-backstage/cli": "^0.1.0",
+    "@backstage/cli": "^0.1.0",
     "@testing-library/jest-dom": "^4.2.4",
     "@testing-library/react": "^9.3.2",
     "@testing-library/user-event": "^7.1.2",
diff --git a/plugins/home-page/package.json b/plugins/home-page/package.json
index 5869b5fde0..2116215e94 100644
--- a/plugins/home-page/package.json
+++ b/plugins/home-page/package.json
@@ -1,12 +1,12 @@
 {
-  "name": "@spotify-backstage/plugin-home-page",
+  "name": "@backstage/plugin-home-page",
   "version": "0.1.0",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
   "private": true,
   "devDependencies": {
-    "@spotify-backstage/cli": "^0.1.0",
-    "@spotify-backstage/core": "^0.1.0",
+    "@backstage/cli": "^0.1.0",
+    "@backstage/core": "^0.1.0",
     "@testing-library/jest-dom": "^4.2.4",
     "@testing-library/react": "^9.3.2",
     "@testing-library/user-event": "^7.1.2",
diff --git a/plugins/home-page/src/components/HomePage/HomePage.test.tsx b/plugins/home-page/src/components/HomePage/HomePage.test.tsx
index 500d53397a..6b2c1bfd11 100644
--- a/plugins/home-page/src/components/HomePage/HomePage.test.tsx
+++ b/plugins/home-page/src/components/HomePage/HomePage.test.tsx
@@ -18,7 +18,7 @@ import React from 'react';
 import { render } from '@testing-library/react';
 import HomePage from './HomePage';
 import { ThemeProvider } from '@material-ui/core';
-import { BackstageTheme } from '@spotify-backstage/core';
+import { BackstageTheme } from '@backstage/core';
 
 describe('HomePage', () => {
   it('should render', () => {
diff --git a/plugins/home-page/src/components/HomePage/HomePage.tsx b/plugins/home-page/src/components/HomePage/HomePage.tsx
index f340b682fa..3ca572b367 100644
--- a/plugins/home-page/src/components/HomePage/HomePage.tsx
+++ b/plugins/home-page/src/components/HomePage/HomePage.tsx
@@ -17,13 +17,7 @@
 import React, { FC } from 'react';
 import { Typography, Link, Grid } from '@material-ui/core';
 import HomePageTimer from '../HomepageTimer';
-import {
-  Content,
-  InfoCard,
-  Header,
-  Page,
-  pageTheme,
-} from '@spotify-backstage/core';
+import { Content, InfoCard, Header, Page, pageTheme } from '@backstage/core';
 import SquadTechHealth from './SquadTechHealth';
 import Table from '@material-ui/core/Table';
 import TableBody from '@material-ui/core/TableBody';
diff --git a/plugins/home-page/src/components/HomePage/SquadTechHealth.tsx b/plugins/home-page/src/components/HomePage/SquadTechHealth.tsx
index 320205367c..c4e55c4dd5 100644
--- a/plugins/home-page/src/components/HomePage/SquadTechHealth.tsx
+++ b/plugins/home-page/src/components/HomePage/SquadTechHealth.tsx
@@ -17,7 +17,7 @@
 import React, { FC } from 'react';
 import { Grid, Typography } from '@material-ui/core';
 
-import { HorizontalScrollGrid, ProgressCard } from '@spotify-backstage/core';
+import { HorizontalScrollGrid, ProgressCard } from '@backstage/core';
 
 const SquadTechHealth: FC<{}> = () => {
   return (
diff --git a/plugins/home-page/src/components/HomepageTimer/HomepageTimer.tsx b/plugins/home-page/src/components/HomepageTimer/HomepageTimer.tsx
index 3407da4012..770f98e762 100644
--- a/plugins/home-page/src/components/HomepageTimer/HomepageTimer.tsx
+++ b/plugins/home-page/src/components/HomepageTimer/HomepageTimer.tsx
@@ -15,7 +15,7 @@
  */
 
 import React, { FC } from 'react';
-import { HeaderLabel } from '@spotify-backstage/core';
+import { HeaderLabel } from '@backstage/core';
 
 const timeFormat = { hour: '2-digit', minute: '2-digit' };
 const utcOptions = { timeZone: 'UTC', ...timeFormat };
diff --git a/plugins/home-page/src/plugin.ts b/plugins/home-page/src/plugin.ts
index 0ace719780..17eb89eb35 100644
--- a/plugins/home-page/src/plugin.ts
+++ b/plugins/home-page/src/plugin.ts
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { createPlugin } from '@spotify-backstage/core';
+import { createPlugin } from '@backstage/core';
 import HomePage from './components/HomePage';
 
 export default createPlugin({
diff --git a/plugins/welcome/package.json b/plugins/welcome/package.json
index 734ba4fea6..47d8be7033 100644
--- a/plugins/welcome/package.json
+++ b/plugins/welcome/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@spotify-backstage/plugin-welcome",
+  "name": "@backstage/plugin-welcome",
   "version": "0.1.0",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
@@ -11,8 +11,8 @@
     "test": "backstage-cli test"
   },
   "devDependencies": {
-    "@spotify-backstage/core": "^0.1.0",
-    "@spotify-backstage/cli": "^0.1.0",
+    "@backstage/core": "^0.1.0",
+    "@backstage/cli": "^0.1.0",
     "@types/testing-library__jest-dom": "5.0.2"
   },
   "dependencies": {
diff --git a/plugins/welcome/src/components/Timer/Timer.tsx b/plugins/welcome/src/components/Timer/Timer.tsx
index 3407da4012..770f98e762 100644
--- a/plugins/welcome/src/components/Timer/Timer.tsx
+++ b/plugins/welcome/src/components/Timer/Timer.tsx
@@ -15,7 +15,7 @@
  */
 
 import React, { FC } from 'react';
-import { HeaderLabel } from '@spotify-backstage/core';
+import { HeaderLabel } from '@backstage/core';
 
 const timeFormat = { hour: '2-digit', minute: '2-digit' };
 const utcOptions = { timeZone: 'UTC', ...timeFormat };
diff --git a/plugins/welcome/src/components/WelcomePage/ErrorButton.test.tsx b/plugins/welcome/src/components/WelcomePage/ErrorButton.test.tsx
index 791937a3b5..6a91a6c202 100644
--- a/plugins/welcome/src/components/WelcomePage/ErrorButton.test.tsx
+++ b/plugins/welcome/src/components/WelcomePage/ErrorButton.test.tsx
@@ -17,7 +17,7 @@
 import React from 'react';
 import { render, fireEvent } from '@testing-library/react';
 import ErrorButton from './ErrorButton';
-import { ApiRegistry, errorApiRef, ApiProvider } from '@spotify-backstage/core';
+import { ApiRegistry, errorApiRef, ApiProvider } from '@backstage/core';
 
 describe('ErrorButton', () => {
   it('should trigger an error', () => {
diff --git a/plugins/welcome/src/components/WelcomePage/ErrorButton.tsx b/plugins/welcome/src/components/WelcomePage/ErrorButton.tsx
index fa73115d18..390c434633 100644
--- a/plugins/welcome/src/components/WelcomePage/ErrorButton.tsx
+++ b/plugins/welcome/src/components/WelcomePage/ErrorButton.tsx
@@ -16,7 +16,7 @@
 
 import React, { FC } from 'react';
 import { Button } from '@material-ui/core';
-import { errorApiRef, useApi } from '@spotify-backstage/core';
+import { errorApiRef, useApi } from '@backstage/core';
 
 const ErrorButton: FC<{}> = () => {
   const errorApi = useApi(errorApiRef);
diff --git a/plugins/welcome/src/components/WelcomePage/WelcomePage.test.tsx b/plugins/welcome/src/components/WelcomePage/WelcomePage.test.tsx
index 9787fa2a9a..b4139e4ed3 100644
--- a/plugins/welcome/src/components/WelcomePage/WelcomePage.test.tsx
+++ b/plugins/welcome/src/components/WelcomePage/WelcomePage.test.tsx
@@ -23,7 +23,7 @@ import {
   ApiProvider,
   ApiRegistry,
   errorApiRef,
-} from '@spotify-backstage/core';
+} from '@backstage/core';
 
 describe('WelcomePage', () => {
   it('should render', () => {
diff --git a/plugins/welcome/src/components/WelcomePage/WelcomePage.tsx b/plugins/welcome/src/components/WelcomePage/WelcomePage.tsx
index 755e19e0ff..69a892a95e 100644
--- a/plugins/welcome/src/components/WelcomePage/WelcomePage.tsx
+++ b/plugins/welcome/src/components/WelcomePage/WelcomePage.tsx
@@ -33,7 +33,7 @@ import {
   pageTheme,
   ContentHeader,
   SupportButton,
-} from '@spotify-backstage/core';
+} from '@backstage/core';
 import ErrorButton from './ErrorButton';
 
 const WelcomePage: FC<{}> = () => {
diff --git a/plugins/welcome/src/plugin.ts b/plugins/welcome/src/plugin.ts
index bdc74209a7..20ec41d4c2 100644
--- a/plugins/welcome/src/plugin.ts
+++ b/plugins/welcome/src/plugin.ts
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { createPlugin } from '@spotify-backstage/core';
+import { createPlugin } from '@backstage/core';
 import WelcomePage from './components/WelcomePage';
 
 export default createPlugin({

From 019032a7a3db535177a21b21c0162413c46e72c2 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Wed, 25 Mar 2020 19:13:14 +0100
Subject: [PATCH 16/23] v0.1.1-alpha.0

---
 lerna.json                     |  7 +++++--
 packages/app/package.json      | 10 +++++-----
 packages/cli/package.json      |  5 +----
 packages/core/package.json     |  7 ++-----
 plugins/home-page/package.json | 12 ++++++------
 plugins/welcome/package.json   |  6 +++---
 6 files changed, 22 insertions(+), 25 deletions(-)

diff --git a/lerna.json b/lerna.json
index 322929db1d..1002c5f9be 100644
--- a/lerna.json
+++ b/lerna.json
@@ -1,6 +1,9 @@
 {
-  "packages": ["packages/*", "plugins/*"],
+  "packages": [
+    "packages/*",
+    "plugins/*"
+  ],
   "npmClient": "yarn",
   "useWorkspaces": true,
-  "version": "0.1.0"
+  "version": "0.1.1-alpha.0"
 }
diff --git a/packages/app/package.json b/packages/app/package.json
index 468e2842db..2aa2c1312e 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -1,15 +1,15 @@
 {
   "name": "@backstage/app",
-  "version": "0.0.0",
+  "version": "0.1.1-alpha.0",
   "private": true,
   "dependencies": {
+    "@backstage/cli": "^0.1.1-alpha.0",
+    "@backstage/core": "^0.1.1-alpha.0",
+    "@backstage/plugin-home-page": "^0.1.1-alpha.0",
+    "@backstage/plugin-welcome": "^0.1.1-alpha.0",
     "@material-ui/core": "^4.9.1",
     "@material-ui/icons": "^4.9.1",
     "@material-ui/lab": "4.0.0-alpha.45",
-    "@backstage/cli": "^0.1.0",
-    "@backstage/core": "^0.1.0",
-    "@backstage/plugin-home-page": "^0.1.0",
-    "@backstage/plugin-welcome": "^0.1.0",
     "@testing-library/jest-dom": "^4.2.4",
     "@testing-library/react": "^9.3.2",
     "@testing-library/user-event": "^7.1.2",
diff --git a/packages/cli/package.json b/packages/cli/package.json
index bf24095c61..f26b13a421 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@backstage/cli",
   "description": "CLI for developing Backstage plugins and apps",
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -24,9 +24,6 @@
     "test": "backstage-cli test",
     "start": "nodemon ."
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "devDependencies": {
     "@types/fs-extra": "^8.1.0",
     "@types/html-webpack-plugin": "^3.2.2",
diff --git a/packages/core/package.json b/packages/core/package.json
index 48bbe83cd6..8adb1307fe 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@backstage/core",
   "description": "Core API used by Backstage plugins and apps",
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -23,9 +23,6 @@
     "lint": "backstage-cli lint",
     "test": "backstage-cli test"
   },
-  "publishConfig": {
-    "access": "public"
-  },
   "dependencies": {
     "@material-ui/core": "^4.9.1",
     "@material-ui/icons": "^4.9.1",
@@ -42,7 +39,7 @@
     "recompose": "0.30.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.1.0",
+    "@backstage/cli": "^0.1.1-alpha.0",
     "@testing-library/jest-dom": "^4.2.4",
     "@testing-library/react": "^9.3.2",
     "@testing-library/user-event": "^7.1.2",
diff --git a/plugins/home-page/package.json b/plugins/home-page/package.json
index 2116215e94..33be457cba 100644
--- a/plugins/home-page/package.json
+++ b/plugins/home-page/package.json
@@ -1,12 +1,14 @@
 {
   "name": "@backstage/plugin-home-page",
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.0",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
   "private": true,
   "devDependencies": {
-    "@backstage/cli": "^0.1.0",
-    "@backstage/core": "^0.1.0",
+    "@backstage/cli": "^0.1.1-alpha.0",
+    "@backstage/core": "^0.1.1-alpha.0",
+    "@material-ui/core": "^4.9.1",
+    "@material-ui/icons": "^4.9.1",
     "@testing-library/jest-dom": "^4.2.4",
     "@testing-library/react": "^9.3.2",
     "@testing-library/user-event": "^7.1.2",
@@ -14,9 +16,7 @@
     "@types/node": "^12.0.0",
     "@types/testing-library__jest-dom": "5.0.2",
     "react": "^16.12.0",
-    "react-dom": "^16.12.0",
-    "@material-ui/core": "^4.9.1",
-    "@material-ui/icons": "^4.9.1"
+    "react-dom": "^16.12.0"
   },
   "scripts": {
     "build": "backstage-cli plugin:build",
diff --git a/plugins/welcome/package.json b/plugins/welcome/package.json
index 47d8be7033..b38977afab 100644
--- a/plugins/welcome/package.json
+++ b/plugins/welcome/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@backstage/plugin-welcome",
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.0",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
   "license": "Apache-2.0",
@@ -11,8 +11,8 @@
     "test": "backstage-cli test"
   },
   "devDependencies": {
-    "@backstage/core": "^0.1.0",
-    "@backstage/cli": "^0.1.0",
+    "@backstage/cli": "^0.1.1-alpha.0",
+    "@backstage/core": "^0.1.1-alpha.0",
     "@types/testing-library__jest-dom": "5.0.2"
   },
   "dependencies": {

From 7910f8e7f1952cf6b910f90dcf29c807e4b02762 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Stefan=20=C3=85lund?= <alund@spotify.com>
Date: Thu, 26 Mar 2020 14:39:20 +0100
Subject: [PATCH 17/23] Add RFCs to README

---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 629bfdc376..9fb99531f9 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ We created Backstage about 4 years ago. While our internal version of Backstage
 
 - 🐇 **Phase 3:** Ecosystem (later) - Everyone's infrastructure stack is different. By fostering a vibrant community of contributors we hope to provide an ecosystem of Open Source plugins/integrations that allows you to pick the tools that match your stack.
 
-Check out our [Milestones](https://github.com/spotify/backstage/milestones) and how they relate to the 3 Phases outlined above.
+Check out our [Milestones](https://github.com/spotify/backstage/milestones) and open [RFCs](https://github.com/spotify/backstage/labels/rfc) how they relate to the three Phases outlined above. 
 
 Our vision for Backstage is for it to become the trusted standard toolbox (read: UX layer) for the open source infrastructure landscape. Think of it like Kubernetes for developer experience. We realize this is an ambitious goal. We can’t do it alone. If this sounds interesting or you'd like to help us shape our product vision, we'd love to talk. You can email me directly: [alund@spotify.com](mailto:alund@spotify.com).
 
@@ -93,6 +93,7 @@ Then open http://localhost/ on your browser.
 
 - [Discord chat](https://discord.gg/MUpMjP2) - Get support or discuss the project
 - [Good First Issues](https://github.com/spotify/backstage/labels/good%20first%20issue) - Start here if you want to contribute
+- [RFCs](https://github.com/spotify/backstage/labels/rfc) - Help shape the technical direction
 - [FAQ](docs/FAQ.md) - Frequently Asked Questions
 - [Code of Conduct](CODE_OF_CONDUCT.md) - This is how we roll
 - Give us a star ⭐️ - If you are using Backstage or think it is an interesting project, we would love a star ❤️

From 8c1a2765e0324a514cc37c8a1a7c54cf5dd8551c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Stefan=20=C3=85lund?= <alund@spotify.com>
Date: Thu, 26 Mar 2020 20:27:25 +0100
Subject: [PATCH 18/23] Add question to FAQ

---
 docs/FAQ.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/FAQ.md b/docs/FAQ.md
index 9b9fff564e..4e742fbd72 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -31,3 +31,10 @@ Bitbucket. We believe that in time there will be plugins that will provide funct
 as well. Hopefully contributed by the community.
 
 And note that implementations of Backstage can be hosted wherever you feel suits your needs best.
+
+## Is Backstage only suitable for developer portals?
+
+No, not really. The core frontend framework could be used for building any large-scale web application where multiple teams are building separate parts of the app, but you want the overall experience to be consistent.
+
+That being said, in [Phase 2](https://github.com/spotify/backstage#project-roadmap) of the project we will add features that are needed for developer portals and systems for managing software ecosystems. Our ambition will be to keep Backstage modular.
+

From abd3caf246039a2824bf1f9e31453145b2535910 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Stefan=20=C3=85lund?= <alund@spotify.com>
Date: Thu, 26 Mar 2020 20:37:32 +0100
Subject: [PATCH 19/23] Update FAQ.md

---
 docs/FAQ.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/FAQ.md b/docs/FAQ.md
index 4e742fbd72..01c3a4f473 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -32,9 +32,11 @@ as well. Hopefully contributed by the community.
 
 And note that implementations of Backstage can be hosted wherever you feel suits your needs best.
 
-## Is Backstage only suitable for developer portals?
+## Can Backstage by used for other things than developer portals?
 
-No, not really. The core frontend framework could be used for building any large-scale web application where multiple teams are building separate parts of the app, but you want the overall experience to be consistent.
+Yes. 
+
+The core frontend framework could be used for building any large-scale web application where multiple teams are building separate parts of the app, but you want the overall experience to be consistent.
 
 That being said, in [Phase 2](https://github.com/spotify/backstage#project-roadmap) of the project we will add features that are needed for developer portals and systems for managing software ecosystems. Our ambition will be to keep Backstage modular.
 

From 580f30f72116995eb49a494e24f823c8436ee2be Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Stefan=20=C3=85lund?= <alund@spotify.com>
Date: Fri, 27 Mar 2020 07:59:12 +0100
Subject: [PATCH 20/23] Link to Blog from README (#397)

* Link to Blog from README

* Update README.md
---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 9fb99531f9..1c20ec8cc6 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,7 @@ Then open http://localhost/ on your browser.
 - [RFCs](https://github.com/spotify/backstage/labels/rfc) - Help shape the technical direction
 - [FAQ](docs/FAQ.md) - Frequently Asked Questions
 - [Code of Conduct](CODE_OF_CONDUCT.md) - This is how we roll
+- [Blog](https://backstage.io/blog/) - Announcements and updates
 - Give us a star ⭐️ - If you are using Backstage or think it is an interesting project, we would love a star ❤️
 
 Or, if you are an open source developer and are interested in joining our team, please reach out to [foss-opportunities@spotify.com ](mailto:foss-opportunities@spotify.com)

From b0329a82612ab6728caf105bae501e4e67c68e1f Mon Sep 17 00:00:00 2001
From: Paul Marbach <pmarbach@spotify.com>
Date: Fri, 27 Mar 2020 09:26:31 -0400
Subject: [PATCH 21/23] fix: install @backstage/core when scaffolding a plugin

---
 packages/cli/templates/default-plugin/package.json.hbs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/cli/templates/default-plugin/package.json.hbs b/packages/cli/templates/default-plugin/package.json.hbs
index 6e416f3287..b2bd6f2c82 100644
--- a/packages/cli/templates/default-plugin/package.json.hbs
+++ b/packages/cli/templates/default-plugin/package.json.hbs
@@ -16,6 +16,7 @@
     "jest-fetch-mock": "^3.0.3"
   },
   "dependencies": {
+    "@backstage/core": "^{{version}}",
     "@material-ui/lab": "4.0.0-alpha.45"
   }
 }

From 894d25b54b5d0c908003626c2a07d6391597e836 Mon Sep 17 00:00:00 2001
From: Vern Burton <me@vernburton.com>
Date: Sat, 28 Mar 2020 18:40:28 -0500
Subject: [PATCH 22/23] updating Dockerfile to pull in custom default.conf to
 overload default file.

---
 Dockerfile            |  1 +
 docker-compose.yml    | 21 ---------------------
 docker/backstage.conf |  9 ---------
 docker/default.conf   | 23 +++++++++++++++++++++++
 4 files changed, 24 insertions(+), 30 deletions(-)
 delete mode 100644 docker-compose.yml
 delete mode 100644 docker/backstage.conf
 create mode 100644 docker/default.conf

diff --git a/Dockerfile b/Dockerfile
index 39d51a35f2..5337207235 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -15,3 +15,4 @@ RUN yarn build
 FROM nginx:mainline
 
 COPY --from=builder /app/packages/app/build /usr/share/nginx/html
+COPY ./docker/default.conf /etc/nginx/conf.d/default.conf
diff --git a/docker-compose.yml b/docker-compose.yml
deleted file mode 100644
index 90c2e6d395..0000000000
--- a/docker-compose.yml
+++ /dev/null
@@ -1,21 +0,0 @@
-version: '3.7'
-services:
-  app:
-    volumes:
-      - app_dir:/app/packages/app/build
-    build: .
-
-  web:
-    ports:
-      - 8080:80
-    volumes:
-      - ./docker/backstage.conf:/etc/nginx/conf.d/backstage.conf
-      - type: volume
-        source: app_dir
-        target: /usr/share/backstage/html
-        volume:
-          nocopy: true
-    image: nginx:mainline
-
-volumes:
-  app_dir:
\ No newline at end of file
diff --git a/docker/backstage.conf b/docker/backstage.conf
deleted file mode 100644
index b309ab0b01..0000000000
--- a/docker/backstage.conf
+++ /dev/null
@@ -1,9 +0,0 @@
-server {
-   listen 80 default_server;
-   root /usr/share/backstage/html;
-   server_name backstage.local;
-   index index.html index.htm;
-   location / {
-       try_files $uri /index.html;
-   }
-}
\ No newline at end of file
diff --git a/docker/default.conf b/docker/default.conf
new file mode 100644
index 0000000000..d01be24dc7
--- /dev/null
+++ b/docker/default.conf
@@ -0,0 +1,23 @@
+server {
+    listen       80;
+    server_name  localhost;
+
+    #charset koi8-r;
+    #access_log  /var/log/nginx/host.access.log  main;
+
+    location / {
+        root   /usr/share/nginx/html;
+        index  index.html index.htm;
+        try_files $uri /index.html;
+    }
+
+    #error_page  404              /404.html;
+
+    # redirect server error pages to the static page /50x.html
+    #
+    error_page   500 502 503 504  /50x.html;
+    location = /50x.html {
+        root   /usr/share/nginx/html;
+    }
+}
+

From 9235807f1407901b65829a0fc1e2a69c5267592e Mon Sep 17 00:00:00 2001
From: Ahmet Soormally <ahmet@mangomm.co.uk>
Date: Fri, 27 Mar 2020 18:47:46 +0000
Subject: [PATCH 23/23] document how to override the default port

Port 3000 is a common port in the development environment.

This documents how you can start backstage with a different port to the default.

Moved section for development environment to own page within docs in order to keep README small.
---
 README.md                                     | 12 ++-----
 docs/getting-started/README.md                |  1 +
 .../development-environment.md                | 35 +++++++++++++++++++
 3 files changed, 38 insertions(+), 10 deletions(-)
 create mode 100644 docs/getting-started/development-environment.md

diff --git a/README.md b/README.md
index 1c20ec8cc6..2145e62fa8 100644
--- a/README.md
+++ b/README.md
@@ -69,16 +69,8 @@ $ yarn start
 
 The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.
 
-### (Optional)Try on Docker
-
-Run the following commands if you have Docker environment
-
-```bash
-$ docker build . -t spotify/backstage
-$ docker run --rm -it -p 80:80 spotify/backstage
-```
-
-Then open http://localhost/ on your browser.
+For more complex development environment configuration, see the 
+[Development Environment](docs/getting-started/development-environment.md) section of the Getting Started docs.
 
 ## Documentation
 
diff --git a/docs/getting-started/README.md b/docs/getting-started/README.md
index c37e61e82f..719e946a7e 100644
--- a/docs/getting-started/README.md
+++ b/docs/getting-started/README.md
@@ -2,6 +2,7 @@
 
 Here is a collection of tutorials that will guide you through setting up and extending an instance of Backstage with your own plugins.
 
+- [Development Environment](development-environment.md)
 - [Create a Backstage plugin](create-a-plugin.md)
 - [Structure of a plugin](structure-of-a-plugin.md)
 - Using Backstage components (TODO)
diff --git a/docs/getting-started/development-environment.md b/docs/getting-started/development-environment.md
new file mode 100644
index 0000000000..e836a0c5d2
--- /dev/null
+++ b/docs/getting-started/development-environment.md
@@ -0,0 +1,35 @@
+# Development Environment
+
+Open a terminal window and start the web app using the following commands from the project root:
+
+```bash
+$ yarn install # may take a while
+
+$ yarn start
+```
+
+The final `yarn start` command should open a local instance of Backstage in your browser, otherwise open one of the URLs printed in the terminal.
+
+By default, backstage will start on port 3000, however you can override this by setting an environment variable `PORT` on your local machine. e.g. `export PORT=8080` then running `yarn start`. Or `PORT=8080 yarn start`.
+
+Once successfully started, you should see the following message in your terminal window:
+
+```
+You can now view @backstage/app in the browser.
+
+  Local:            http://localhost:8080
+  On Your Network:  http://192.168.1.224:8080
+```
+
+### (Optional)Try on Docker
+
+Run the following commands if you have Docker environment
+
+```bash
+$ docker build . -t spotify/backstage
+$ docker run --rm -it -p 80:80 spotify/backstage
+```
+
+Then open http://localhost/ on your browser.
+
+[Back to Docs](README.md)