Skip to content

Commit

Permalink
Clarify readme by moving dev info to contributing guide, change .env …
Browse files Browse the repository at this point in the history 
…default
  • Loading branch information
@ChaseCares
ChaseCares authored Feb 19, 2024
1 parent c072c74 commit 0f95a34
Show file tree
Hide file tree
Showing 3 changed files with 93 additions and 97 deletions.
45 changes: 45 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Contributing to Broadcast Box

Contributing to broadcast box is greatly appreciated. We are happy to give guidance, answer questions and review PRs.

## Getting Started

Broadcast Box is made up of two parts. The server is written in Go and is in charge
of ingesting and broadcasting WebRTC. The frontend is in react and connects to the Go
backend.

### Configuring

Configurations can be made in [.env.development](./.env.development).

### Frontend

React dependencies are installed by running `npm install` in the `web` directory, then run `npm start` to serve the frontend. You should see the following:

```console
Compiled successfully!

You can now view broadcast-box in the browser.

Local: http://localhost:3000
On Your Network: http://192.168.1.57:3000

Note that the development build is not optimized.
To create a production build, use npm run build.

webpack compiled successfully
```

### Backend

Go dependencies are automatically installed.

To run the Go server run `APP_ENV=development go run .` in the root of this project. You will see the logs
like the following.

```console
2022/12/11 15:22:47 Loading `.env.development`
2022/12/11 15:22:47 Running HTTP Server at `:8080`
```

To use Broadcast Box navigate to: `http://localhost:3000`. In your broadcast tool of choice, you will broadcast to `http://localhost:8080/api/whip`.
135 changes: 43 additions & 92 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,15 @@
- [Broadcasting](#broadcasting)
- [Broadcasting (GStreamer, CLI)](#broadcasting-gstreamer-cli)
- [Playback](#playback)
- [Building](#building)
- [Installing Dependencies](#installing-dependencies)
- [Getting Started](#getting-started)
- [Configuring](#configuring)
- [Local Development](#local-development)
- [Production](#production-build)
- [Running](#running)
- [Network Test on Start](#network-test-on-start)
- [Environment variables](#environment-variables)
- [Building From Source](#building-from-source)
- [Frontend](#frontend)
- [Backend](#backend)
- [Docker](#docker)
- [Docker Compose](#docker-compose)
- [Environment variables](#environment-variables)
- [Network Test on Start](#network-test-on-start)
- [Design](#design)

## What is Broadcast Box
Expand All @@ -26,6 +25,8 @@ Broadcast Box lets you broadcast to others in sub-second time. It was designed
to be simple to use and easily modifiable. We wrote Broadcast Box to show off some
of the cutting edge tech that is coming to the broadcast space.

Want to contribute to the development of Broadcast Box? See [Contributing](./CONTRIBUTING.md).

### Sub-second Latency

Broadcast Box uses WebRTC for broadcast and playback. By using WebRTC instead of
Expand Down Expand Up @@ -74,8 +75,7 @@ If you want a direct connection between OBS and your browser see [OBS2Browser][o
## Using

To use Broadcast Box you don't even have to run it locally! A instance of Broadcast Box
is hosted at [b.siobud.com](https://b.siobud.com). If you wish to run it locally skip to
[Running](#running)
is hosted at [b.siobud.com](https://b.siobud.com). If you wish to run it locally skip to [Getting Started](#getting-started)

### Broadcasting

Expand Down Expand Up @@ -126,99 +126,71 @@ the latency of 120 milliseconds observed.

![Example have potential latency](./.github/img/broadcastView.png)

## Building

Broadcast Box is made up of two parts. The server is written in Go and is in charge
of ingesting and broadcasting WebRTC. The frontend is in react and connects to the Go
backend.

While developing `webpack-dev-server` is used for the frontend. In production the Go server
can be used to serve the HTML/CSS/JS directly. These are the instructions on how to run all
these parts.

### Installing Dependencies

Go dependencies are automatically installed.
## Getting Started

react dependencies are installed by running `npm install` in the `web` directory.
Broadcast Box is made up of two parts. The server is written in Go and is in charge of ingesting and broadcasting WebRTC. The frontend is in react and connects to the Go backend. The Go server can be used to serve the HTML/CSS/JS directly. Use the following instructions to build from source or utilize [Docker](#docker) / [Docker Compose](#docker-compose).

### Configuring

Both projects use `.env` files for configuration. For development `.env.development` is used
and in production `.env.production` is used.

For Go setting `APP_ENV` will cause `.env.production` to be loaded.
Otherwise `.env.development` is used.
Configurations can be made in [.env.production](./.env.production), although the defaults should get things going.

For react App the dev server uses `.env.development` and `npm run build`
uses `.env.production`
### Building From Source

### Local Development
#### Frontend

For local development you will run the Go server and webpack directly.
React dependencies are installed by running `npm install` in the `web` directory and `npm run build` will build the frontend.

To run the Go server run `go run .` in the root of this project. You will see the logs
like the following.
If everything is successful, you should see the following:

```console
2022/12/11 15:22:47 Loading `.env.development`
2022/12/11 15:22:47 Running HTTP Server at `:8080`
```

To run the web front open the `web` folder and execute `npm start` if that runs successfully you will be greeted with.

```console
Compiled successfully!

You can now view broadcast-box in the browser.
> broadcast-box@0.1.0 build
> dotenv -e ../.env.production react-scripts build

Local: http://localhost:3000
On Your Network: http://192.168.1.57:3000
Creating an optimized production build...
Compiled successfully.

Note that the development build is not optimized.
To create a production build, use npm run build.
File sizes after gzip:

webpack compiled successfully
53.51 kB build/static/js/main.12067218.js
2.27 kB build/static/css/main.8738ee38.css
...
```

To use Broadcast Box you will open `http://localhost:3000` in your browser. In your broadcast tool of choice
you will broadcast to `http://localhost:8080/api/whip`.

### Production Build
#### Backend

For production usage Go will server the frontend and backend.
Go dependencies are automatically installed.

To run the Go server run `APP_ENV=production go run .` in the root of this project. You will see the logs like the following.
To run the Go server, run `go run .` in the root of this project, you should see the following:

```console
2022/12/11 16:02:14 Loading `.env.production`
2022/12/11 16:02:14 Running HTTP Server at `:8080`
```

If `APP_ENV` was set properly `.env.production` will be loaded.
To use Broadcast Box navigate to: `http://<YOUR_IP>:8080`. In your broadcast tool of choice, you will broadcast to `http://<YOUR_IP>:8080/api/whip`.

To build the frontend execute `npm run build` in the `web` directory. You will get the following output.
### Docker

```console
> broadcast-box@0.1.0 build
> dotenv -e ../.env.production react-scripts build
A Docker image is also provided to make it easier to run locally and in production. The arguments you run the Dockerfile with depending on
if you are using it locally or a server.

Creating an optimized production build...
Compiled successfully.
If you want to run locally execute `docker run -e UDP_MUX_PORT=8080 -e NAT_1_TO_1_IP=127.0.0.1 -p 8080:8080 -p 8080:8080/udp seaduboi/broadcast-box`.
This will make broadcast-box available on `http://localhost:8080`. The UDPMux is needed because Docker on macOS/Windows runs inside a NAT.

File sizes after gzip:
If you are running on AWS (or other cloud providers) execute. `docker run --net=host -e INCLUDE_PUBLIC_IP_IN_NAT_1_TO_1_IP=yes seaduboi/broadcast-box`
broadcast-box needs to be run in net=host mode. broadcast-box listens on random UDP ports to establish sessions.

53.51 kB build/static/js/main.12067218.js
2.27 kB build/static/css/main.8738ee38.css
...
```
### Docker Compose

To use Broadcast Box you will open `http://localhost:8080` in your browser. In your broadcast tool of choice
you will broadcast to `http://localhost:8080/api/whip`.
A Docker Compose is included that uses LetsEncrypt for automated HTTPS. It also includes Watchtower so your instance of Broadcast Box
will be automatically updated every night. If you are running on a VPS/Cloud server this is the quickest/easiest way to get started.

## Running
```console
export URL=my-server.com
docker-compose up -d
```

### Environment Variables
## Environment Variables

The backend can be configured with the following environment variables.

Expand Down Expand Up @@ -274,27 +246,6 @@ Join the Discord and we are ready to help! To debug check the following.

If you wish to disable the test set the environment variable `NETWORK_TEST_ON_START` to false.

### Docker

A Docker image is also provided to make it easier to run locally and in production. The arguments you run the Dockerfile with depending on
if you are using it locally or a server.

If you want to run locally execute `docker run -e UDP_MUX_PORT=8080 -e NAT_1_TO_1_IP=127.0.0.1 -p 8080:8080 -p 8080:8080/udp seaduboi/broadcast-box`.
This will make broadcast-box available on `http://localhost:8080`. The UDPMux is needed because Docker on macOS/Windows runs inside a NAT.

If you are running on AWS (or other cloud providers) execute. `docker run --net=host -e INCLUDE_PUBLIC_IP_IN_NAT_1_TO_1_IP=yes seaduboi/broadcast-box`
broadcast-box needs to be run in net=host mode. broadcast-box listens on random UDP ports to establish sessions.

### Docker Compose

A Docker Compose is included that uses LetsEncrypt for automated HTTPS. It also includes Watchtower so your instance of Broadcast Box
will be automatically updated every night. If you are running on a VPS/Cloud server this is the quickest/easiest way to get started.

```console
export URL=my-server.com
docker-compose up -d
```

## Design

The backend exposes three endpoints (the status page is optional, if hosting locally).
Expand Down
10 changes: 5 additions & 5 deletions main.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -168,16 +168,16 @@ func corsHandler(next func(w http.ResponseWriter, r *http.Request)) http.Handler
}

func main() {
if os.Getenv("APP_ENV") == "production" {
log.Println("Loading `" + envFileProd + "`")
if os.Getenv("APP_ENV") == "development" {
log.Println("Loading `" + envFileDev + "`")

if err := godotenv.Load(envFileProd); err != nil {
if err := godotenv.Load(envFileDev); err != nil {
log.Fatal(err)
}
} else {
log.Println("Loading `" + envFileDev + "`")
log.Println("Loading `" + envFileProd + "`")

if err := godotenv.Load(envFileDev); err != nil {
if err := godotenv.Load(envFileProd); err != nil {
log.Fatal(err)
}
}
Expand Down

0 comments on commit 0f95a34

Please sign in to comment.