Merge pull request #1007 from spotify/freben-patch-1-1

backend: document how to start in dev mode

packages/backend/README.md

@@ -12,7 +12,48 @@ app. Until then, feel free to experiment here!
 
 ## Development
 
-To run the backend in watch mode, use `yarn start`.
+To run the example backend, first go to the project root and run
+
+```bash
+yarn install
+yarn build
+```
+
+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 SENTRY_TOKEN=x 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.
+
+The backend starts up on port 7000 per default.
+
+## Populating The Catalog
+
+If you want to use the catalog functionality, you need to add so called locations
+to the backend. These are places where the backend can find some entity descriptor
+data to consume and serve.
+
+To get started, you can issue the following after starting the backend:
+
+```bash
+curl -i \
+  -H "Content-Type: application/json" \
+  -d '{"type":"github","target":"https://github.com/spotify/backstage/blob/master/plugins/catalog-backend/fixtures/two_components.yaml"}' \
+  localhost:7000/catalog/locations
+```
+
+After a short while, you should start seeing data on `localhost:7000/catalog/entities`.
+
+If you changed the `type` to `file` in the command above, and set the `target`
+to the absolute path of a YAML file on disk, you could consume your own experimental data.
+
+The catalog currently runs in-memory only, so feel free to try it out, but it will
+need to be re-populated on next startup.
 
 ## Documentation