Oryx Documentation

This guide describes how to build and test an SRS droplet image for the DigitalOcean Marketplace using Packer.

1. Install Packer and DigitalOcean Plugin

On macOS, use Homebrew to install Packer and the required DigitalOcean plugin:

brew tap hashicorp/tap &&
brew install hashicorp/tap/packer &&
PACKER_LOG=1 packer plugins install github.com/digitalocean/digitalocean

2. Build the Image

You can either set the DIGITALOCEAN_TOKEN environment variable manually or extract it from your doctl config. Run the build from the scripts/setup-droplet directory:

(export DIGITALOCEAN_TOKEN=$(grep market "${HOME}/Library/Application Support/doctl/config.yaml" |grep -v context |awk '{print $2}') &&
cd scripts/setup-droplet && packer build srs.json)

3. Test the Droplet

1. Create a Test Droplet: Use doctl to create a droplet from the newly created snapshot.
2. Prepare Environment: SSH into the droplet to set up directories, upload test media (source.200kbps.768x320.flv), and install necessary tools like ffmpeg.
3. Run Tests: Execute ./test/oryx.test on the droplet via SSH to verify RTMP, HTTP, and SRT endpoints.

4. Cleanup

After testing, delete the droplet and the snapshot (if submitting to the marketplace, the snapshot should be removed).

doctl compute droplet delete oryx-test --context market --force

To build an SRS image for TencentCloud Lighthouse, follow these steps:

1. Configure Credentials: Create a TencentCloud Secret and save it to ~/.lighthouse/.env with the following keys:

   • LH_ACCOUNT
   • LH_PROD
   • SECRET_ID
   • SECRET_KEY

2. Build the Image: Use the provided helper scripts to create a CVM instance, build the image, and share it. The process involves creating a token, running scripts/tools/tencent-cloud/helper.sh create-cvm.py, building via scripts/setup-lighthouse/build.sh, and finally sharing the image.

3. Verify the Image: Create a test CVM instance using scripts/tools/tencent-cloud/helper.sh create-verify.py and run the oryx.test suite against the new instance to ensure functionality.

4. Cleanup: Remove the test CVM, images, and snapshots using the remove-cvm.py and remove-image.py helpers.

# Example: Create a CVM instance and build the image
rm -f .tmp/lh-*.txt &&
echo "$(openssl rand -base64 32 | tr -dc 'a-zA-Z0-9' | head -c 16)A0" >.tmp/lh-token.txt &&
VM_TOKEN=$(cat .tmp/lh-token.txt) bash scripts/tools/tencent-cloud/helper.sh create-cvm.py --id $(pwd)/.tmp/lh-instance.txt &&
bash scripts/tools/tencent-cloud/helper.sh query-cvm-ip.py --instance $(cat .tmp/lh-instance.txt) --id $(pwd)/.tmp/lh-ip.txt &&
echo "Instance: $(cat .tmp/lh-instance.txt), IP: ubuntu@$(cat .tmp/lh-ip.txt), Password: $(cat .tmp/lh-token.txt)" && sleep 5 &&
bash scripts/setup-lighthouse/build.sh --ip $(cat .tmp/lh-ip.txt) --os ubuntu --user ubuntu --password $(cat .tmp/lh-token.txt) &&
bash scripts/tools/tencent-cloud/helper.sh create-image.py --instance $(cat .tmp/lh-instance.txt) --id $(pwd)/.tmp/lh-image.txt &&
bash scripts/tools/tencent-cloud/helper.sh share-image.py --image $(cat .tmp/lh-image.txt) &&
echo "Image: $(cat .tmp/lh-image.txt) created and shared." &&
bash scripts/tools/tencent-cloud/helper.py remove-cvm.py --instance $(cat .tmp/lh-instance.txt)

To serve HLS streams over HTTPS, use the ossrs/oryx:nginx-hls-cdn-https image.

1. Prepare Certificates: Generate or provide an SSL certificate (.crt) and a private key (.key).
2. Run with SSL: Mount your certificate files into the container at /data/config/ and map port 443.
3. Environment Variables:
   • ORYX_SERVER: The IP and port of your origin server.
   • SRS_M3U8_EXPIRE: (Optional) Set to your SRS hls_fragment duration or desired refresh time. Default is 10s.
   • SRS_TS_EXPIRE: (Optional) Set the expiration time for .ts files. Default is 3600s.

# 1. Generate self-signed certificates
openssl genrsa -out nginx.key 2048
openssl req -new -x509 -key nginx.key -out nginx.crt -days 3650 -subj "/CN=nginx01.your-domain.com"

# 2. Run NGINX Edge with HTTPS
docker run --rm -it --name oryx-nginx01 -d \
  -p 80:80 -p 443:443 \
  -e ORYX_SERVER=<YOUR_ORYX_IP>:2022 \
  -v $(pwd)/nginx.key:/data/config/nginx.key \
  -v $(pwd)/nginx.crt:/data/config/nginx.crt \
  ossrs/oryx:nginx-hls-cdn-https

You can use NGINX as a proxy/cache for HLS streams generated by Oryx.

Development

Build the NGINX HLS CDN image using: docker build -t ossrs/oryx:nginx-hls-cdn scripts/nginx-hls-cdn

Running as a Proxy

To run NGINX as a proxy in Docker, pass the ORYX_SERVER environment variable pointing to your Oryx instance:

ORYX_SERVER=$(ifconfig en0 | grep 'inet ' | awk '{print $2}')
docker run --rm -it -p 80:80 --name nginx -e ORYX_SERVER=${ORYX_SERVER}:2022 ossrs/oryx:nginx-hls-cdn

Production Setup

To set up a production HLS Edge server:

1. Install Oryx (via BT, aaPanel, or Docker).
2. Create a new WebSite in your web server (e.g., Nginx) to proxy requests to the NGINX HLS Edge server.
3. Use the following Nginx configuration for the proxy site:

location /tools/ {
  proxy_pass http://localhost:2022;
}
location / {
  proxy_no_cache 1;
  proxy_cache_bypass 1;
  add_header X-Cache-Status-Proxy $upstream_cache_status;
  proxy_pass http://localhost:23080;
}

4. Start the NGINX HLS Edge server container, mapping port 80 to 23080:

docker run --rm -it -e ORYX_SERVER=$PIP:2022 -p 23080:80 --name oryx-nginx01 -d ossrs/oryx:nginx-hls-cdn

Important Note on CORS: The NGINX cache stores CORS headers. If a request is cached without CORS headers, subsequent requests with an Origin header that requires CORS will still receive the cached version without CORS.

This guide covers building and deploying the SSL certificate infrastructure for HTTPS support.

1. Domain Setup: Create a domain record using doctl.
2. Build Platform Image: Build the platform:latest Docker image and save it as a tarball.
3. Deploy to Server: Transfer the tarball to the target server, load it, and tag it as ossrs/oryx:$version.
4. BT Plugin Development:
   • Build the BT plugin using scripts/setup-bt/auto/zip.sh.
   • Unzip the plugin into /www/server/panel/plugin on the target server.
   • Run the install.sh script to install the plugin.
5. Site Configuration: Use the provided BT API scripts (bt_api_remove_site.py, bt_api_create_site.py, bt_api_setup_site.py) and setup.sh to configure the site and Nginx.

Environment Variables for BT: Set these in your .bashrc on the server:

• BT_KEY
• PYTHONIOENCODING=UTF-8

# Build and save the platform image
docker build -t platform:latest -f Dockerfile .
docker save -o platform.tar platform:latest

# Build the BT plugin
bash scripts/setup-bt/auto/zip.sh --output $(pwd)/build --extract

# Install the BT plugin on the server
ssh root@$LNAME.$LDOMAIN unzip -q bt-oryx.zip -d /www/server/panel/plugin
ssh root@$LNAME.$LDOMAIN bash /www/server/panel/plugin/oryx/install.sh install

To develop the ORYX plugin for the BT (Baota) panel, you must run a development container that mounts your local build as a plugin and integrates with your BT account credentials.

Prerequisites

1. BT Account Info: Bind the Docker container to your BT account to obtain userInfo.json. Save it to $HOME/.bt/userInfo.json.
2. BT HTTP API: Enable the HTTP API and save the resulting api.json to $HOME/.bt/api.json.

Development Workflow

1. Start the Dev Container: Run the provided docker run command (see code) to mount your local build/oryx directory into the BT plugin path.
2. Build Platform Image: Build the platform:latest image and save it as a tarball.
3. Load Image into BT Container: Use docker exec to load the platform image into the running bt container and tag it with the appropriate version.
4. Build and Install Plugin: Use zip.sh to package the plugin and run the install.sh script inside the container.
5. Setup Site: Use the provided Python scripts (bt_api_create_site.py, etc.) and setup.sh to configure the site within the BT environment.
6. DNS Setup: Add srs.stack.local to the /etc/hosts file of both the bt container and the oryx container to allow internal communication.
7. Testing: Run the oryx.test suite inside the bt container to verify the installation and API functionality.

Deployment

After successful testing, the plugin is located at build/bt-oryx.zip. This file can be uploaded directly to the production BT panel's application store.

# Start the BT development container
docker rm -f bt aapanel 2>/dev/null &&
BT_KEY=$(cat $HOME/.bt/api.json |awk -F token_crypt '{print $2}' |cut -d'"' -f3) &&
docker run -p 80:80 -p 443:443 -p 7800:7800 -p 1935:1935 -p 8000:8000/udp -p 10080:10080/udp \
    --env CANDIDATE=$(ifconfig en0 |grep 'inet ' |awk '{print $2}') \
    -v $(pwd)/build/oryx:/www/server/panel/plugin/oryx \
    -v $HOME/.bt/userInfo.json:/www/server/panel/data/userInfo.json \
    -v $HOME/.bt/api.json:/www/server/panel/config/api.json -e BT_KEY=$BT_KEY \
    --privileged -v /sys/fs/cgroup:/sys/fs/cgroup:rw --cgroupns=host \
    -d --rm -it -v $(pwd):/g -w /g --name=bt ossrs/bt-plugin-dev:1