datarhei Core

You can quickly deploy datarhei Core using Docker. This setup initializes the API with default credentials and maps configuration and data volumes to your host machine.

1. Run the Docker container:

docker run --name core -d \
    -e CORE_API_AUTH_USERNAME=admin \
    -e CORE_API_AUTH_PASSWORD=secret \
    -p 8080:8080 \
    -v ${HOME}/core/config:/core/config \
    -v ${HOME}/core/data:/core/data \
    datarhei/core:latest

2. Access the Swagger API documentation at http://<host-ip>:8080/api/swagger/index.html.

3. Authorize in Swagger using Basic Auth with the credentials:

• Username: admin
• Password: secret

The Restreamer v1 database importer reads a legacy Restreamer v1 database (v1.json, created with version 0.6.7 or later) and transforms it into the new database format, including UI metadata. It also updates the configuration file with static redirect routes for the player, snapshot, and m3u8 paths to ensure a seamless migration.

Important Migration Rules:

• Version Compatibility: If the v1 database was created with a version older than 0.6.7, the importer assumes the input stream contains an H264 video track.
• Safety Check: The importer will not perform an import if a non-empty new database already exists. This prevents overwriting existing data in non-fresh installations.
• Input Requirements: A v1.json file must be present in the directory defined by RS_DB_DIR or RS_CONFIGFILE.

Depending on your hardware and requirements (e.g., GPU acceleration), choose the appropriate Docker image:

• datarhei/core:latest: Standard image (supports AMD64, ARM64, ARMv7).
• datarhei/core:cuda-latest: Optimized for Nvidia CUDA 11.7.1 (AMD64).
• datarhei/core:rpi-latest: Optimized for Raspberry Pi / OMX/V4L2-M2M (AMD64/ARMv7).
• datarhei/core:vaapi-latest: Optimized for Intel VAAPI (AMD64).

The server exposes a GraphQL interface at /api/graph/query. This allows for complex queries involving Restreamer processes, monitoring data, and logs.

• Playground: Access the GraphQL playground at /api/graph to test queries visually.
• Query Endpoint: Send POST requests to /api/graph/query with your GraphQL payload.

The /v3 route group provides the primary programmatic interface for managing the datarhei core. Most endpoints are protected by JWT if configured.

Available v3 Groups:

• Restreamer: Manage processes (/v3/process), skills, and metadata.
• Playout: Manage playout status, keyframes, and error frames (/v3/process/:id/playout/...).
• Filesystems: List and manage files across mounted filesystems (/v3/fs).
• Protocols: List RTMP and SRT channels (/v3/rtmp, /v3/srt).
• System: Manage configuration (/v3/config), sessions (/v3/session), and logs (/v3/log).
• Metrics: Describe and collect metrics (/v3/metrics).

The import process follows a strict safety pattern to prevent data loss:

1. Configuration Validation: The tool validates the configuration and merges it with environment variables. If errors are found, the process exits.
2. V1 Database Detection: It looks for a v1.json file in the directory specified by cfg.DB.Dir.
3. Empty Target Check: It loads the current datastore (db.json). If the current database is not empty (!data.IsEmpty()), the import is aborted to prevent overwriting existing data.
4. Data Transformation: If the target is empty, it uses importV1 to rewrite the old database format into the new one.
5. Legacy Route Injection: After a successful import, it modifies the configuration to add static routes that mimic old Restreamer URLs, ensuring backward compatibility for clients using legacy endpoints.

The importer uses the same environment variables as the Restreamer core to locate data and define inputs:

• RS_CONFIGFILE: Used to locate the configuration file and the directory containing the databases.
• RS_DB_DIR: Used to locate the database directory.
• Input Device Variables: All environment variables used to define USB devices or Rapsicam are respected and used to define the inputs during the transformation process.

The migration tool handles specific breaking changes in FFmpeg command-line arguments based on the major version.

Supported Version Transitions

• FFmpeg 4 to 5: For RTSP inputs (rtsps?://), the option -stimeout is replaced with -timeout.
• FFmpeg 5 to 6: Currently no argument changes are applied, but the tool updates the FFVersion metadata.

Constraints

• The tool supports target FFmpeg major versions up to 6.
• It requires a minimum FFmpeg major version of 4.
• The FFVersion in the process configuration is updated to include a caret prefix (e.g., ^5.0.0) to indicate compatibility.

The app/import binary is a CLI tool used to migrate data from an old Restreamer v1 database (v1.json) to the current Restreamer database format (db.json).

To run the import, ensure the following environment variables are set:

• CORE_CONFIGFILE: The path to the configuration file.
• FFmpeg related variables (via the configuration) to ensure the import uses the correct binary.

The tool performs the following steps:

1. Loads the configuration from the specified file.
2. Merges configuration with environment variables.
3. Checks for the existence of a v1.json file in the database directory.
4. If the new database (db.json) is empty, it imports the data from v1.json.
5. Updates the configuration to include static routes for legacy URL compatibility (e.g., /hls/live.stream.m3u8, /images/live.jpg, and /player.html).

To start the Core application, use the api.New function to create an API instance, followed by app.Start() to begin processing. The application supports dynamic configuration reloading: if app.Start() returns api.ErrConfigReload, you should call app.Stop() and then app.Reload() to apply new settings without a full restart. For a clean shutdown, call app.Destroy() after receiving an interrupt signal.

// 1. Initialize the API with a config file location and an error output
app, err := api.New(configfile, os.Stderr)
if err != nil {
    // handle error
}

// 2. Start the application
err = app.Start()

// 3. Handle config reload if Start returns api.ErrConfigReload
if err == api.ErrConfigReload {
    app.Stop()
    err = app.Reload()
}

// 4. Graceful shutdown
app.Destroy()

The application determines its configuration file location using the CORE_CONFIGFILE environment variable. You can resolve this path using store.Location(os.Getenv("CORE_CONFIGFILE")) to ensure the path is correctly formatted for the api.New constructor.

configfile := store.Location(os.Getenv("CORE_CONFIGFILE"))
app, err := api.New(configfile, os.Stderr)