paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 45 Packages Projects Releases Wiki Activity

Merge pull request #111 from spotify/rugvip/readme

Browse Source 
move install instructions to readme + move docker-compose
This commit is contained in:
Patrik Oldsberg
2020-02-24 11:47:12 +01:00
committed by GitHub
parent 855c062444 8c9b04b240
commit 4abdc11012
7 changed files with 63 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Brewfile
-18
View File
@@ -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"
Procfile
-2
View File
@@ -1,2 +0,0 @@
backend: docker-compose up --build
frontend: cd frontend/ && yarn install && yarn start
README.md
+27 -19
View File
@@ -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
# <ExampleComponent />
```
## 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
backend/.env
+1
View File
@@ -0,0 +1 @@
COMPOSE_PROJECT_NAME=backstage
backend/README.md
+15
View File
@@ -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 .
```
docker-compose.yaml → backend/docker-compose.yaml
+10 -10
View File
@@ -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
proto/README.md
+10 -8
View File
@@ -4,19 +4,21 @@ Collection of all Backstage protobuf definitions.
## Usage
Managed with [Prototool](https://github.com/uber/prototool), install instructions at <https://github.com/uber/prototool/blob/dev/docs/install.md>
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: