From 8c9b04b24097a348468a91754b374df73a641f2c Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Mon, 24 Feb 2020 11:01:14 +0100 Subject: [PATCH] move install instructions to readme + move docker-compose --- Brewfile | 18 -------- Procfile | 2 - README.md | 46 +++++++++++-------- backend/.env | 1 + backend/README.md | 15 ++++++ .../docker-compose.yaml | 20 ++++---- proto/README.md | 18 ++++---- 7 files changed, 63 insertions(+), 57 deletions(-) delete mode 100644 Brewfile delete mode 100644 Procfile create mode 100644 backend/.env create mode 100644 backend/README.md rename docker-compose.yaml => backend/docker-compose.yaml (69%) 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: