diff --git a/Brewfile b/Brewfile
deleted file mode 100644
index 8e43ffdd88..0000000000
--- a/Brewfile
+++ /dev/null
@@ -1,18 +0,0 @@
-###
-# This will download all Homebrew dependencies.
-###
-
-# Shared
-brew "git"
-brew "docker"
-brew "docker-compose"
-brew "protobuf"
-brew "prototool"
-cask "docker"
-
-# Frontend
-brew "node@12"
-brew "yarn"
-
-# Backend
-brew "go"
diff --git a/Procfile b/Procfile
deleted file mode 100644
index 063f838e54..0000000000
--- a/Procfile
+++ /dev/null
@@ -1,2 +0,0 @@
-backend: docker-compose up --build
-frontend: cd frontend/ && yarn install && yarn start
diff --git a/README.md b/README.md
index 75bbf2a0a7..363147a162 100644
--- a/README.md
+++ b/README.md
@@ -8,15 +8,13 @@ Backstage is an open platform for building developer portals.
## Getting started
-### Install Dependencies with Homebrew and Yarn
+### Install Dependencies
-Run the following to install relevant dependencies (such as Git, Docker, etc):
+To run the frontend, you will need to have [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), [NodeJS](https://nodejs.org/en/download/), and [yarn](https://classic.yarnpkg.com/en/docs/install#mac-stable) installed.
-```bash
-# If you don't have Homebrew, run the following command:
-# $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
-$ make install
-```
+For running the backend, depending on your OS, you need [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/), [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/), or for Linux, [docker](https://docs.docker.com/install/) and [docker-compose](https://docs.docker.com/compose/install/#install-compose-on-linux-systems).
+
+The above dependencies are enough to run and work on the Backstage frontend packages. To develop backend services, there are some more tools to install, see [backend/README.md](backend/README.md). To update protobuf definitions, you will need another set of tools, see [proto/README.md](proto/README.md).
### Secrets
@@ -26,24 +24,28 @@ To setup secrets, copy the `secrets.env.example` to `secrets.env` as such:
$ make init-secrets
```
-### Protobuf Definitions
-
-To generate the Protobuf definitions in Go and TypeScript, run the following command from the root to run [Prototool](https://github.com/uber/prototool):
-
-```bash
-$ make build-protocol-definitions
-```
-
-See [proto/README.md](proto/README.md) for more information.
-
## Running Locally
-Once you've installed all dependencies, start serving the frontend using `yarn`:
+The full local system consists of a collection of backend services, as well as a web application. From the root of the project directory, run the following in a terminal to start up all backend services locally:
```bash
-$ make start
+cd backend
+
+docker-compose up --build
```
+Once the backend services are up and running, open a separate terminal window and start the web app using the following commands from the project root:
+
+```bash
+cd frontend
+
+yarn # 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.
+
## Plugins
### Creating a Plugin
@@ -71,6 +73,12 @@ $ vim frontend/packages/app/src/App.tsx
#
```
+## Protobuf Definitions
+
+The protobuf definitions are all found in the `/proto` folder in the project root. They are used to generate code for gRPC communication for both the frontend and backend. The generated code is checked into version control though, so unless you want to change the protobuf definitions you don't need to install any tooling.
+
+Information about how to work with the protobuf definitions can be found inside [proto/README.md](proto/README.md).
+
## Documentation
## License
diff --git a/backend/.env b/backend/.env
new file mode 100644
index 0000000000..e1b17b2d4c
--- /dev/null
+++ b/backend/.env
@@ -0,0 +1 @@
+COMPOSE_PROJECT_NAME=backstage
diff --git a/backend/README.md b/backend/README.md
new file mode 100644
index 0000000000..2768cdb52f
--- /dev/null
+++ b/backend/README.md
@@ -0,0 +1,15 @@
+# Backstage Backends
+
+## Installing Dependencies
+
+### Go
+
+To build and run the backend services directly, you need to have Go installed, installation instructions can be found [here](https://golang.org/doc/install#install).
+
+## Usage
+
+To run any backend service, go into its directory and run:
+
+```bash
+go run .
+```
diff --git a/docker-compose.yaml b/backend/docker-compose.yaml
similarity index 69%
rename from docker-compose.yaml
rename to backend/docker-compose.yaml
index 06d0ccd1ce..e59bd76511 100755
--- a/docker-compose.yaml
+++ b/backend/docker-compose.yaml
@@ -6,7 +6,7 @@ services:
proxy:
container_name: boss-proxy
build:
- context: backend/proxy
+ context: proxy
restart: unless-stopped
ports:
- "8080:80"
@@ -14,31 +14,31 @@ services:
identity:
container_name: boss-identity
build:
- context: backend
+ context: .
args:
service: identity
restart: unless-stopped
volumes:
- - ./backend/identity/identity-data.json:/app/identity-data.json
+ - ./identity/identity-data.json:/app/identity-data.json
inventory:
container_name: boss-inventory
build:
- context: backend
+ context: .
args:
service: inventory
restart: unless-stopped
volumes:
- - ./backend/inventory/inventory.db:/app/inventory.db
+ - ./inventory/inventory.db:/app/inventory.db
builds:
container_name: boss-builds
build:
- context: backend
+ context: .
args:
service: builds
restart: unless-stopped
- env_file: secrets.env
+ env_file: ../secrets.env
depends_on:
- inventory
links:
@@ -50,12 +50,12 @@ services:
links:
- inventory
build:
- context: backend
+ context: .
args:
service: scaffolder
base_image: scaffolder
restart: unless-stopped
volumes:
- - ./backend/scaffolder/templates:/app/templates:ro
+ - ./scaffolder/templates:/app/templates:ro
- env_file: secrets.env
+ env_file: ../secrets.env
diff --git a/proto/README.md b/proto/README.md
index e052080b22..540157708c 100644
--- a/proto/README.md
+++ b/proto/README.md
@@ -4,19 +4,21 @@ Collection of all Backstage protobuf definitions.
## Usage
-Managed with [Prototool](https://github.com/uber/prototool), install instructions at
+Prodobuf definitions are managed with [Prototool](https://github.com/uber/prototool).
-## Install Dependencies
+## Installing Dependencies
### Prototool
-```bash
-$ brew install prototool
-```
+See [installation instructions](https://github.com/uber/prototool/blob/dev/docs/install.md). On MacOS you can use `brew install prototool`.
+
+### Go
+
+You will need to have Go installed, along with a properly set up `GOPATH` and `$GOPATH/bin` added to your `PATH`, follow the instructions [here](https://golang.org/doc/install#install).
### protoc-gen-go
-This will enable code generation in Go for interacting with gRPC-Web. You will need to have `protoc-gen-go` available in your path. You can find out more information here: https://github.com/golang/protobuf
+This will enable code generation for Go. You will need to have `protoc-gen-go` available in your path. You can find out more information here: https://github.com/golang/protobuf
```bash
$ go get -u github.com/golang/protobuf/protoc-gen-go
@@ -31,10 +33,10 @@ Installation instructions are found at https://github.com/grpc/grpc-web#code-gen
## Generating Code
-To generate the Protobuf definitions in Go and TypeScript, run the following command from the root with [Prototool](https://github.com/uber/prototool):
+To generate the Protobuf definitions in Go and TypeScript, run the following command inside the `proto/` directory with [Prototool](https://github.com/uber/prototool):
```bash
-$ prototool generate ./proto
+$ prototool generate
```
This will generate the respective "generated" files in the following folders: