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

@@ -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
 

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)

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)