Setup
You can start the ugc multimedia service by executing ugc-multimedia.jar either directly or by calling java -jar ugc-multimedia.jar which is an executable. JVMARGS can be provided either as JAVA_OPTS in an ugc-multimedia.conf file next to the ugc-multimedia.jar or as part of the command when using java -jar ugc-multimedia.jar. The content of an ugc-multimedia.conf file might be:
JAVA_OPTS='-Xmx1g -Dlogging.config=/cms/ugc-multimedia/config/logback.xml -Dspring.config.location=/cms/ugc-multimedia/config/application.yml'
Starting the ugc multimedia service with java would look like this for the same properties:
java -Xmx1g -Dlogging.config=/cms/ugc-multimedia/config/logback.xml -Dspring.config.location=/cms/ugc-multimedia/config/application.yml -jar ugc-multimedia.jar
It is necessary to use a reverse proxy as described below and on the "Reverse Proxy" documentation page.
Configuration
The configuration of the service is done with a file called application.yml. It's written in the commonly used YAML format. In this example all values are the default values.
spring:
jpa:
hibernate:
ddl-auto: <mode> # database intitialization mode, e.g. update (see Spring documentation for details)
database-platform: <org.hibernate.dialect> # org.hibernate.dialect.MySQL5InnoDBDialect or org.hibernate.dialect.Oracle12cDialect
database: <database-type> # type of database, either mysql or oracle
datasource:
url: <url-to-database>
# url to database which depends on the type of database, could be either jdbc:mysql://<host>:<port>/<db>?serverTimezone=UTC or jdbc:oracle:thin:@//<host>:<port>/<SID>
username: <user> # user to access the database
password: <pwd> # password of that user
driver-class-name: <driver-class> # driver class to access the database, depends on type of database and may be either com.mysql.cj.jdbc.Driver or oracle.jdbc.OracleDriver
servlet:
multipart:
max-file-size: <file-size> # maximum size of a single file to upload, e.g. 20MB
max-request-size: <request-size> # maximum size of all files uploaded in a single request, e.g. 20 MB
management:
endpoints:
web:
exposure:
include: 'Prometheus' # exposes the specified endpoint. Default: 'Prometheus'
endpoint:
prometheus:
enabled: true # enables the Prometheus endpoint. Default: true
server :
port : <port> # port where the endpoints of the ugc multimedia service can be accessed
sophora:
client:
server-connection:
urls: http://<host>:<port> # url to sophora servers the service should connect to, may be several to overcome a unreachable sophora server instance
username: <sophora-user> # the user the service uses to login to sophora
password: <sophora-pwd> # the password of the user
storage:
type: fs # type of storage to use for the multimedia files. fs for filesystem and s3 for an s3 compatible storage is supported. One of the storage options has to be configured.
fs: # configuration for fs storage type
baseDir: <path> # path to the location where to store files, e.g. /binaries/
# type: s3 # example configuration for s3 storage
# s3:
# accessKeyId: <accessKeyId>
# secretAccessKey: <secretAccessKey>
# bucketName: <bucketName>
# host: <host>
multimedia:
allowedMimeTypes: # MIME types that might be uploaded. May be either a type or a type with a subtype (e.g. 'audio', 'audio/mpeg') and may also contain a suffix (e.g. 'image/svg+xml'). Default: 'audio', 'video'
- <mimeType1>
- <mimeType2>
headlineProperty: <title-property> # the title that is displayed in the document overview (sophora-content:title)
# definition of the markers with which entries can be marked and filtered in the editorial-ui. The list can contain any number of entries
markers:
- key: <key1> # unique key
label: <label1> # the label
colorValue: <color-value1> # a valid css color ("Red", "Blue", "#F0F8FF", ...)
- key: <key2>
label: <label2>
colorValue: <color-value1>
auth: # when the following two properties are set, the requests of all endpoints starting with '/secure' will be protected with HTTP basic authentication
username: <username>
password: <password>
# configuration for the swagger ui
springdoc:
swagger-ui:
url: "/v3/api-docs"
# to disable the default swagger url
disable-swagger-default-url: true
# enable to continue using the Swagger UI when basic authentication is enabled
csrf:
enabled: true
clamd:
clamdHost: <clamd host> # host of the clamd service to scan multimedia uploads for viruses
clamdPort: <clamd port> # port of the clamd service to scan multimedia uploads for viruses
timeoutInMS: <milliseconds> # timeout in MS of the connection to the clamd service
clamdFileStorageDir: <path> # path of the location where the file to be tested should be stored, e.g. clamdTest/ After the scan the file will be deleted.
httpStatusCodeForVirus: <HTTP code> # HTTP response code in case a virus is detected by the clamd service. Default is 200
cleanup:
binaries:
enabled: false # enables the clean up job. Default is false.
cronSchedule: "0 59 * * * *" # the time at which the cron job is triggered. Default is 1 minute before the hour
regexForBinaries: "[a-z0-9-]{36,}" # the regex to filter binaries to be deleted by the cleanup job. Default is the regex for UUIDs.
binaryWasAtLeastNotModifiedSinceHours: 72 # the hours since a binary file was last modified. Only binaries that have at least not been changed up to this configured point in time are deleted. Default is 72 hours.
metadata:
enabled: false # enables the clean up job for missing binaries. Default is false
cronSchedule: "0 59 * * * *" # the time at which the cron job is triggered. Default is 1 minute before the hour
minimumAgeInHours: 72 # the hours since metadata have been created. Only metadata that have been created at least the number of hours ago are deleted. Default is 72 hours.
headers:
crossOriginUrl: "http://localhost:8080" # a url from which cross-origin requests are allowed. Default is "http://localhost:8080"
websocket:
allowedOrigin: http://host:port # an allowed origin of the websocket, which is used to check for new multimedia content of a UGC instance. Required only when running the ugc editorial UI with a reverse proxy.
Clamd can be configured to scan uploads for viruses. If no configuration is made, there is no virus check and all files are uploaded to your storage.
Endpoints
The endpoints of the UGC multimedia service are documented by the interactive Swagger UI and are specified by the OpenAPI standard. It can be accessed at the URL http://<hostname>:<port>/swagger-ui.html. (With UGC versions before 4.3.0 it can be accessed at the URL http://<hostname>:<port>/api-ui/)
It is necessary to use a reverse proxy to distribute requests to the UGC multimedia service and the UGC Webapp. We provide example configurations for Nginx and the Apache HTTP Server on the "Reverse Proxy" documentation page. Ensure that requests to the following paths and all subpaths are forwarded to the multimedia service. See Swagger UI for a complete list of endpoints.
/public/binary/public/multimedia/secure/binary/secure/multimedia/websocket/multimedia
/public/ endpoints. Adjust your reverse proxy and network configurations accordingly.Additionally, HTTP basic authentication can be enabled for the /secure/ endpoints, as shown in the configuration section above.
Usage
The submission of multimedia is done via the endpoint "/public/binary/saveBinaryAndCreateMultimedia". In the body of the request, two request parts are used: the file, which can be an audio or video file, and a multimediaDto. The content type of the multimediaDto must be 'application/json' and accepts an object in the following format:
{
"description": "string",
"externalId": "string",
"headline": "string",
"userId": "string",
"username": "string"
}
Below is an example of how to send a request to this endpoint from the frontend using JavaScript:
const multimediaFormData = new FormData();
multimediaFormData.append('multimediaDto', new Blob([
multimediaDto
], {
type: "application/json"
}))
multimediaFormData.append("file", $("#multimediaData")[0].files[0]);
$.ajax({
url: saveMultimediaObjectUrl,
type: 'POST',
data: multimediaFormData,
dataType: 'json',
processData: false,
enctype: 'multipart/mixed',
contentType: false
})
The multimedia entries submitted in this way can be managed via the editorial ui, which has a new tab in the "multimedia" navigation if the addon has been activated.
Storage
There are two storage options available. With type: fs multimedia files can be saved in the filesystem. type: s3 allows them to be uploaded to an s3 compatible cloud storage. One of both storage options has to be configured. You have to configure bucketName, accessKeyId, secretAccessKey and the host.
