You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit fcdb70f
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/_config.yml
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ color_scheme: bug
6
6
description: Broadcast Universal Gateway
7
7
show_downloads: true
8
8
9
-
footer_content: "BUG was created in <a href='https://bbc.co.uk/news'>BBC News</a>, by <a href='https://github.com/geoffhouse'>Geoff House</a> and <a href='https://github.com/ryanmccartney'>Ryan McCartney</a>."
9
+
footer_content: "BUG was created at the <a href='https://bbc.co.uk/'>BBC</a>, by <a href='https://github.com/geoffhouse'>Geoff House</a> and <a href='https://github.com/ryanmccartney'>Ryan McCartney</a>."
Control and monitor a wide range of equipment from a single web interface.
14
+
BUG is a web-based system for **controlling and monitoring broadcast and media equipment from a single interface**.
14
15
15
-
You can run BUG on a server within your network. A single web page then allows you to add panels that control equipment. Examples include, network switches, video and audio codecs, video matrixes and many more.
16
+
Run BUG on a server within your network and access it through a browser. From one web page, you can add panels to control and observe a wide range of devices and services — including network switches, video and audio codecs, video matrices, and more.
16
17
17
18
18
19
19
-
# Getting Started
20
+
##Getting started
20
21
21
-
-[Installation](./pages/installation)- Installation guide for any operating system
22
-
-[Modules](./pages/modules)- A list of equipment that can be controlled and implemented functionality
22
+
-[Installation](./pages/installation)— Install BUG on any supported operating system
23
+
-[Modules](./pages/modules)— See which devices and services can be controlled, and what functionality is available
23
24
24
-
# Development
25
+
##Development
25
26
26
-
We welcome [development](./pages/development) of additional modules for BUG. A module adds additional control or monitoring functionality to BUG. In principle a module normally represents control of a specific piece of hardware or a service. For example a single module exists to control Blackmagic Videohub matrices and another modules to monitor and report on a NewTek NDI discovery service.
27
+
BUG is designed to be extended. We welcome [development](./pages/development) of additional modules that add new control or monitoring capabilities.
27
28
28
-
An instance of a module is a panel. Multiple panels of the same type can co-exist in BUG. Learn more about [developing](./pages/development) your own below;
29
+
A **module** typically represents a specific piece of hardware or service. For example:
30
+
31
+
- a module for controlling Blackmagic Videohub matrices
32
+
- a module for monitoring a NewTek NDI discovery service
33
+
34
+
Each module can be instantiated one or more times as **panels** within the BUG interface, allowing multiple devices of the same type to be controlled simultaneously.
35
+
36
+
To learn more about developing your own modules, see:
BUG is just one of many Open Source projects at the BBC. Check out the full catalog - [https://www.bbc.co.uk/opensource/](https://www.bbc.co.uk/opensource/).
44
+
BUG is one of many open source projects developed at the BBC.
45
+
Explore the full catalogue at [https://www.bbc.co.uk/opensource/](https://www.bbc.co.uk/opensource/).
Copy file name to clipboardExpand all lines: docs/pages/architecture.md
+43-35Lines changed: 43 additions & 35 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,68 +7,76 @@ has_children: false
7
7
8
8
# Architecture
9
9
10
-
BUG makes a few underlying assumptions built into its architecture that will guide you in developing modules for it. A module's backend exists within its own docker container. The frontend is loaded by BUG core
10
+
BUG is built around a modular, containerized architecture designed to simplify control and monitoring of broadcast equipment. Understanding the assumptions and principles of this architecture is important when developing new modules.
11
11
12
-
BUG runs entirely in Docker. It can be run locally, but this is designed for development purposes only.
12
+
## Core Principles
13
13
14
-
BUG is made up of a number of containers. Every BUG instance will have at least the following containers
14
+
- Each module is self-contained: one module per function.
15
+
- Modules are designed to be independent but can interact via APIs if needed.
16
+
- Focus on simplicity: aim to implement ~80% of a device’s functionality.
17
+
- BUG is mobile-first: UI components are designed to scale across screen sizes.
18
+
- Performance matters: consider the load on devices and frequency of data polling.
19
+
- Modules run in Docker containers, isolating their backend logic from the core system.
20
+
- Module memory is volatile: any temporary data should not be relied upon for persistent state.
Each module is then allocated its own container, an isolated environment to carry out backend monitoring, control and data acquisition functions associated with controlling broadcast infrastructure.
26
+
- BUG Core – serves the frontend UI, manages configuration, and orchestrates modules.
27
+
- Mongo – stores persistent configuration and module data.
Panels communicate only with the BUG Core API. Workers within module containers fetch data directly from devices or external services and write to the module’s Mongo database. The frontend reads data from the BUG Core, not directly from devices or module containers.
49
44
50
-
Configs contain panel configurations. This configuration is stored in BUG core and pushed to panels on either start or update.
45
+
### Key Points
51
46
52
-
Each module is responsible for providing a base config page accessible in the module router from;
47
+
- Workers handle device communication asynchronously.
48
+
- The frontend interacts only with BUG Core, not module containers.
49
+
- Central Mongo databases are per-panel and facilitate sharing data between workers.
50
+
- NodeCache or other local caches can be used within containers for temporary data.
53
51
54
-
`/config`
52
+
## Module Configuration
55
53
56
-
Any config input or form should be wrapped in a PanelConfig component with a save button.
54
+
Panel configuration is persistent and stored in BUG Core. Module containers receive their configuration when started or updated.
55
+
56
+
- Each module should provide a base config page accessible at `/config`.
57
+
- Config forms should use the `PanelConfig` component to ensure consistent behavior:
57
58
58
59
```
59
-
<PanelConfig>
60
60
61
+
<PanelConfig>
62
+
<!-- form fields -->
61
63
</PanelConfig>
62
64
```
63
65
64
-
The API route `/api/panel/config/${panelId}` uses the HTTP action PUT and accepts a config object. Any valid fields are MERGED with the existing config. Any invalid fields are ignored. ??? Should we check and passed config against the `module.json` deafulConfig ???
66
+
- The API route `/api/panel/config/${panelId}` accepts a PUT request with a config object.
67
+
- Valid fields are merged with existing configuration; invalid fields are ignored.
68
+
- Field validation is the responsibility of the module developer.
65
69
66
-
Responsibility for validating fields rests with the module developer.
70
+
Persistent configuration includes things like IP addresses, credentials, or default module options. Temporary runtime data should be stored in the module’s container database or cache.
67
71
68
72
## Module Memory is Volatile
69
73
70
-
Anything created in a module's container during operation should not be viewed as persistent. While it is true that this data in fact persists for as long as the container does you should design modules in such a way that operation could continue without this data.
74
+
Anything stored in a module’s container during runtime should not be considered permanent. Containers can be restarted, rebuilt, or removed at any time.
71
75
72
-
Leading on from this configuration that should persist is managed and stored by BUG core and passed to the container when it is created, started or changes are made to the config in BUG core.
76
+
- Design modules to function correctly even if runtime data is lost.
77
+
- Persistent config should always be stored in BUG Core and passed to the module container.
78
+
- Use the panel-specific Mongo database for temporary or frequently-updated data.
79
+
80
+
---
73
81
74
-
Each module has access to a mongo database named as the panel ID that can be used as desired by the module developer. It functions in a similar way to a cache facilitating the sharing of data between workers.
82
+
This architecture ensures that BUG remains scalable, modular, and resilient while providing clear boundaries between persistent configuration, frontend UI, and module runtime logic.
Copy file name to clipboardExpand all lines: docs/pages/development/capabilities.md
+6-3Lines changed: 6 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,13 +5,16 @@ parent: Development
5
5
nav_order: 2
6
6
---
7
7
8
-
# Development - Module Capabilities
8
+
# Module capabilities
9
9
10
-
Each module type can support one or more capabilities. These are standardised API endpoints to allow data flow between modules.
10
+
Modules can expose one or more **capabilities**.
11
+
A capability is a **standardised API endpoint** that allows data to be shared between modules in a consistent way.
12
+
13
+
Capabilities make it possible for modules to consume information provided by other modules without needing to know their internal implementation.
11
14
12
15
## dhcp-server
13
16
14
-
This capability is used primary for network routers which provide DHCP servers. It can be used to provide 'friendly' names in other modules when only the IP address is known.
17
+
This capability is used primary for network routers which provide DHCP servers. It can be used to provide 'friendly' names in other modules when only the MAC or IP address is known.
Copy file name to clipboardExpand all lines: docs/pages/development/docker.md
+39-13Lines changed: 39 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,30 +7,56 @@ nav_order: 10
7
7
8
8
# Docker and BUG
9
9
10
-
BUG's main application runs in a docker container, it speaks to a separate database in a separate container.
11
-
When you start a panel the main BUG application will build a docker container and launch it on your system and then speak to it via an API.
12
-
This enables BUG to perform very different monitoring and control tasks without continually adjusting the core BUG code.
10
+
BUG runs its main application in a **Docker container**, with a separate container for its database.
11
+
When you start a panel, the core BUG application **builds and launches a dedicated container** for that panel, then communicates with it via an API.
13
12
14
-
Below we've gathered a few helpful terminal commands that'll help you work with the docker cli and debug inside a panel's container.
13
+
This containerised architecture allows BUG to handle a wide variety of monitoring and control tasks **without modifying the core application code**. It also allows individual panels to be restarted independently of each other and the core services.
14
+
15
+
Below are some useful Docker commands to help you **monitor, debug, and manage BUG containers**.
16
+
17
+
---
15
18
16
19
## Checking BUG status
17
20
18
-
Verify your containers are running using the `docker ps` command.
21
+
Use the following command to see which containers are running:
22
+
23
+
```bash
24
+
docker ps
25
+
```
26
+
27
+
Find the one named `bug` and make sure it's not in a `restarting` mode.
28
+
To look at the logs (terminal) of the core container use:
29
+
30
+
```bash
31
+
docker logs bug
32
+
```
19
33
20
34
## Check individual container outputs
21
35
22
-
To look at the logs (terminal) of the core container use;
36
+
All running panels will have a relevant docker container, identifiable by their panel id. This is the same as the one shown when you navigate to the panel in the Web UI.
37
+
38
+
To view the logs of a particular panel:
39
+
40
+
```bash
41
+
docker logs yourlongpanelid
42
+
```
43
+
44
+
## BUG system actions
23
45
24
-
`docker logs bug_app`
46
+
To perform any of these actions, navigate to the installation folder containing the `docker-compose.yml` file (usually `/opt/bug`).
25
47
26
-
Where `bug_app` is the name of the container that can be seen from `docker ps`. You could also add a panel id here to view a panel's terminal output
48
+
### Stop BUG
27
49
28
-
## Stop BUG
50
+
To stop all BUG services and containers
29
51
30
-
To stop the bug, all it's services and containers use;
52
+
```
53
+
docker compose down --remove-orphans
54
+
```
31
55
32
-
`docker compose down --remove-orphans`
56
+
### Start BUG
33
57
34
-
## Detaching from the Terminal
58
+
This will start the BUG core web service and database, but not any previously-built individual panel containers. You'll have to enable these in the BUG UI.
35
59
36
-
Using the flag `-d` with docker-compose detaches the container output stream from the terminal
Copy file name to clipboardExpand all lines: docs/pages/development/layout.md
+36-24Lines changed: 36 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,35 +5,47 @@ parent: Development
5
5
nav_order: 2
6
6
---
7
7
8
-
BUG's project structure is documented here - what types of files are in each folder. What there general functions are and in some case what is passed to and from the functions they contain.
8
+
# Project Layout
9
9
10
-
## /src/routes
10
+
This page describes the structure of the BUG project, the purpose of each major folder under `src/`, and how responsibilities are separated across the codebase. BUG’s source is organised to keep frontend, backend, and modules clear and maintainable.
11
11
12
-
- should contain route logic
13
-
- if request params are needed, they should be extracted and passed from here
14
-
- no req or resp should be passed to services
15
-
- should return http error codes if problem
16
-
- no logging?
12
+
---
13
+
14
+
## `/src/client`
15
+
16
+
- Contains the **frontend application** for BUG.
17
+
- UI code for rendering panels, controls, dashboards, and views.
18
+
- Communicates with the backend using REST APIs and modules.
19
+
- Includes React component logic and assets.
20
+
21
+
---
22
+
23
+
## `/src/modulebuilder`
17
24
18
-
## /src/services
25
+
- Contains code responsible for **creating and managing module scaffolding**.
26
+
- Includes templates or builders that generate module structures.
27
+
- Used internally when generating new modules or updating existing ones.
28
+
- Handles registration and initialization of modules with the server.
19
29
20
-
- one file for each service 'user', 'config', 'docker'
21
-
- lots of business logic
22
-
- can combine results from multiple sources
23
-
- or just direct model
24
-
- may well be complex
30
+
---
31
+
32
+
## `/src/modules`
33
+
34
+
- Contains the implementations of all available module types.
35
+
- Each module type contains a `client` and `container` folder:
36
+
-`client` files are bundled into the main UI build.
37
+
-`container` files are used to build the Docker image that runs when a panel is created for this module type.
38
+
- Each Docker container runs a web service exposing its own API endpoints.
39
+
- You can define any endpoints; however, a few endpoints are **mandatory** (`/api/status`, `/api/config`).
25
40
26
-
## /src/models
41
+
---
42
+
43
+
## `/src/server`
27
44
28
-
-read a file, access a db, save a file etc
29
-
-divided up by logical group, but includes all CRUD for that thing
30
-
-no business logic - access only
45
+
-Contains the Node.js code and runs an Express.js server for the main BUG backend application.
46
+
-Provides the API for the user interface and manages panel lifecycle via Docker.
47
+
-Loads modules, orchestrates their lifecycle, and configures middleware, error handling, and global services.
31
48
32
-
## /src/modules
49
+
---
33
50
34
-
- the following api endpoints should be defined:
35
-
> - /api/status - returns an array including:
36
-
> - state: 'starting', 'ready', 'failed'
37
-
> - /api/config - should be able to receive a config object and save it locally
38
-
> - module logging should be to console only
39
-
> - module APIs must follow JSON output standard (status, data, error)
51
+
This layout keeps BUG **organized and modular**, separating frontend UI, backend API layers, and module logic for easier maintenance and scalable development.
0 commit comments