Skip to content

Commit 1416822

Browse files
brookgagnonbrookgagnon
authored
Update INSTALL.md
1 parent 7cbae7f commit 1416822

1 file changed

Lines changed: 150 additions & 19 deletions

File tree

‎INSTALL.md‎

Lines changed: 150 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,30 @@
11
# OpenBroadcaster - Server Installation Instructions
22

3+
34
## Dependencies
45

5-
- A web server with a web environment available (e.g., Apache, Nginx)
6-
- PHP 8.2 or higher
6+
- A web server with a web environment available (Nginx recommended)
7+
- A [supported PHP version](https://www.php.net/supported-versions.php) (not end of life)
78
- MySQL or MariaDB database server
89
- Composer (PHP dependency manager)
910
- Node.js and npm (Node Package Manager)
1011

12+
1113
## Required PHP Modules
1214

13-
Make sure the following PHP modules are installed and enabled:
15+
Make sure the following PHP modules are installed and enabled (listed as Ubuntu/Debian packages):
16+
17+
- php-mysql (for MySQL database connectivity)
18+
- php-mbstring (for multi-byte string handling)
19+
- php-xml (for XML parsing)
20+
- php-gd (for image manipulation)
21+
- php-curl (for making HTTP requests)
22+
- php-imagick (for advanced image processing)
1423

15-
- mysql (for MySQL database connectivity)
16-
- mbstring (for multi-byte string handling)
17-
- xml (for XML parsing)
18-
- gd (for image manipulation)
19-
- curl (for making HTTP requests)
20-
- imagick (for advanced image processing)
2124

2225
## Required Packages
2326

24-
Install the following Ubuntu / Debian packages, or the equivalent for your operating system.
27+
Install the following Ubuntu/Debian packages, or the equivalent for your operating system.
2528

2629
- festival (for text-to-speech functionality)
2730
- imagemagick (for image manipulation)
@@ -30,40 +33,168 @@ Install the following Ubuntu / Debian packages, or the equivalent for your opera
3033
- libavfilter-extra (extra filters for ffmpeg)
3134
- vorbis-tools (for Ogg Vorbis audio encoding)
3235

33-
## Installation Steps
36+
37+
## Files and Database Setup
3438

3539
1. Copy the OpenBroadcaster Server files to your web server's document root directory.
3640

37-
2. Navigate to the cloned repository directory within the web document root and run the following command to install PHP and JavaScript dependencies.
41+
2. Navigate to the web document root and run the following command to install PHP and JavaScript dependencies.
3842

3943
```
4044
composer install && npm install
4145
```
4246

43-
5. Create a new MySQL or MariaDB database for OpenBroadcaster and import the `db/clean.sql` file to set up the initial database structure.
47+
3. Create a new MySQL or MariaDB database for OpenBroadcaster and import the `db/clean.sql` file to set up the initial database structure.
48+
49+
4. Copy the `config.sample.php` file to `config.php` and open it in a text editor. Set the required configuration items, such as database connection details and other settings specific to your environment.
50+
51+
5. To improve performance, uncomment the `OB_SENDFILE_HEADER` line appropriate for your web server in `config.php`. Ensure your web server and site configuration supports this (see Nginx example below).
52+
53+
```
54+
// define('OB_SENDFILE_HEADER', 'X-Sendfile'); // set appropriate SENDFILE header based on server (apache)
55+
// define('OB_SENDFILE_HEADER', 'X-Accel-Redirect'); // set appropriate SENDFILE header based on server (nginx)
56+
// define('OB_SENDFILE_HEADER', 'X-LIGHTTPD-send-file'); // set appropriate SENDFILE header based on server (lighttpd)
57+
```
58+
59+
## Users and Permissions
60+
61+
1. Create a dedicated user for OpenBroadcaster. This user should be the same user used by the web server PHP process, the background task service, and any manual use of the CLI tool.
62+
63+
2. Ensure the paths specified in `config.php` exist and are writable by this user.
64+
65+
66+
## PHP Configuration
67+
68+
A default PHP installation is generally adequate, though you will likely want to increase these values:
69+
70+
| Name | Value | Description |
71+
| - | - | - |
72+
| memory_limit | 512M | Increase memory allowed per request |
73+
| post_max_size | 1024M | Increase max post size to handle file uploads |
74+
75+
Note that increasing `upload_max_filesize` should not be necessary given how OpenBroadcaster handles file uploads.
76+
77+
Additionally, PHP should be configured to run as the dedicated OpenBroadcaster user. The following is an example PHP pool.d file at `/etc/php/8.3/fpm/pool.d/openbroadcaster.conf`:
78+
79+
```
80+
[openbroadcaster]
81+
user = openbroadcaster
82+
group = openbroadcaster
83+
listen = /run/php/php8.3-openbroadcaster-fpm.sock
84+
listen.owner = www-data
85+
listen.group = www-data
86+
pm = dynamic
87+
pm.max_children = 5
88+
pm.start_servers = 2
89+
pm.min_spare_servers = 1
90+
pm.max_spare_servers = 3
91+
92+
php_admin_value[memory_limit] = 512M
93+
php_admin_value[post_max_size] = 1024M
94+
```
95+
96+
This assumes the dedicated OpenBroadcaster user is `openbroadcaster`, and that Nginx is running as `www-data`.
97+
98+
## Nginx Configuration
99+
100+
1. Make sure 'mjs' is added as an extension for application/javascript in `/etc/nginx/mime.types`:
101+
102+
```
103+
application/javascript js mjs;
104+
```
105+
106+
2. Use the following as a starting point for your site configuration, updating values as necessary:
107+
108+
```
109+
server {
110+
listen 80;
111+
server_name openbroadcaster.example.com;
112+
113+
root /home/openbroadcaster/www/public;
114+
index index.php;
115+
116+
location / {
117+
try_files $uri $uri/ =404;
118+
}
119+
120+
# disallow access to files and directories starting with a period
121+
location ~ /\. {
122+
deny all;
123+
access_log off;
124+
log_not_found off;
125+
}
126+
127+
# php file handling
128+
location ~ \.php$ {
129+
include snippets/fastcgi-php.conf;
130+
fastcgi_pass unix:/run/php/php8.3-openbroadcaster-fpm.sock;
131+
fastcgi_buffer_size 32k;
132+
fastcgi_buffers 8 32k;
133+
fastcgi_busy_buffers_size 64k;
134+
}
135+
136+
# rewrite for API URLs
137+
location ^~ /api/ {
138+
try_files $uri $uri/ /api.php$is_args$args;
139+
}
140+
141+
# allow access to files via X-Accel-Redirect
142+
location /home/openbroadcaster/files/ {
143+
internal;
144+
alias /home/openbroadcaster/files/;
145+
}
146+
147+
# allow larger data posts and file uploads
148+
# this should have the same value as PHP's post_max_size
149+
client_max_body_size 1024M;
150+
}
151+
```
44152

45-
6. Copy the `config.sample.php` file to `config.php` and open it in a text editor. Set the required configuration items, such as database connection details and other settings specific to your environment.
153+
## Verifying Install and Running Updates
46154

47-
7. Run the following command to validate your configuration file. Correct any errors displayed in red.
155+
1. Run the following command to validate your configuration file. Correct any errors displayed in red.
48156

49157
```
50158
tools/cli/ob check
51159
```
52160

53-
6. Run the following command to install database updates. This may take a few minutes to complete.
161+
2. Run the following command to install database updates. This may take a few minutes to complete.
54162

55163
```
56164
tools/cli/ob updates run all
57165
```
58166

59-
8. Set the password for the default admin user by running the following command. Enter a secure password when prompted.
167+
3. Set the password for the default admin user by running the following command. Enter a secure password when prompted.
60168

61169
```
62170
tools/cli/ob passwd admin
63171
```
64172

65-
9. Set up a cron job to run the `cron.php` script regularly. This script is responsible for clearing old cache and unused upload files. The following is an example crontab entry.
173+
174+
## Service Configuration
175+
176+
The last step is to ensure `tools/cli/ob cron monitor` is running continuously in the background. To do this, you may set up a service, `/etc/systemd/system/ob.service`, as follows. Be sure to update the `ExecStart` path and `User` as necessary.
177+
178+
```
179+
[Unit]
180+
Description=OB Background Tasks
181+
After=network.target
182+
183+
[Service]
184+
Type=simple
185+
User=openbroadcaster
186+
ExecStart=/path/to/ob/tools/cli/ob cron monitor
187+
Restart=always
188+
RestartSec=10
189+
190+
[Install]
191+
WantedBy=multi-user.target
192+
```
193+
194+
Then enable and start the service (as root or with sudo):
66195

67196
```
68-
* * * * * /path/to/openbroadcaster/tools/cli/ob cron run
197+
systemctl daemon-reload
198+
systemctl enable ob
199+
systemctl start ob
69200
```

0 commit comments

Comments
 (0)