Installation

Two methods are available to install the tool:

1. Docker Compose (Recommended)

1.1 Configuring the docker-compose.yml file

IMPORTANT

Please read the comments in the configuration file for more information and make sure to modify crucial parts like passwords, paths, etc.

Create a docker-compose.yml which contains the following content:

networks:
  stream-rec:

services:
  # Backend service
  backend:
    #   Uses the latest main branch image
    image: streamrec/stream-rec:latest
    #    container name, you can change it to any name you like
    container_name: stream-rec
    restart: unless-stopped
    #    port mapping, you can change the port to any port you like
    ports:
      - "12555:12555"
    networks:
      - stream-rec
    volumes:
      # Host machine path binding to container path, storage path mapping
      - "./downloads:/opt/records"
      # Rclone configuration file path binding
      - "./rclone:/root/.config/rclone"
    environment:
      # Timezone, by default is Europe/Paris.
      - TZ=Europe/Paris
      # Proxy settings, comment it out if you don't need a proxy.
      #- HTTP_PROXY=http://192.168.110.10:7890
      # Log level, by default is info. `DEBUG` logs are useful for debugging, but they can be very verbose.
      - LOG_LEVEL=INFO
      # CONTAINER database path
      - DB_PATH=/opt/records
      # CONTAINER download path for the first initialization
      - DOWNLOAD_PATH=/opt/records
      # FIRST USE LOGIN secret, YOU CAN CHANGE IT TO ANY STRING YOU LIKE
      - LOGIN_SECRET=123
      # Group ID
      - PGID=1000
      # User ID
      - PUID=1000
      
  # Frontend service
  frontend:
    #   Uses the latest main branch image
    image: streamrec/stream-rec-front:latest
    container_name: stream-rec-frontend
    restart: unless-stopped
    #   port mapping, you can change the port to any port you like
    ports:
      - "15275:15275"
    networks:
      - stream-rec
    depends_on:
      - backend
    environment:
      #    timezone, by default is Europe/Paris.
      - TZ=Europe/Paris
      # Backend api url, made up of the container name and port.
      # DO NOT CHANGE IT if you don't know what you are doing.
      # Make sure the port is the same as the backend port.
      - API_URL=http://backend:12555/api
      # Secret for next-auth, YOU CAN CHANGE IT TO ANY STRING YOU LIKE
      - NEXTAUTH_SECRET=6chtw8GBN3BO
      # CLIENT url, used by next-auth to redirect to login page.
      # Should be the address which the user types in the browser to access the frontend.
      # Make sure the port is the same as the frontend port.
      - NEXTAUTH_URL=http://localhost:15275/
      # WS_API_URL, CLIENT websocket url. Used for live status updates.
      # This should use the ip address of the deployed server.
      # Below is an example of using localhost, you can change it to the ip address of the deployed server.
      # For example, if backend is deployed on the server ip address 12.12.12.12, with port 12555, then you should change it to ws://12.12.12.12:12555/live/update
      - WS_API_URL=ws://localhost:12555/live/update

Backend environment variables

Environment	Description
LOG_LEVEL	Determines the verbosity of logging output for the backend. Common levels include debug, info, warn, and error, which control the detail and amount of log information generated.
HTTP_PROXY	Specifies the URL of the proxy server that the application should use for outgoing HTTP requests. This can be used to route requests through a specific network path or to bypass network restrictions.
DB_PATH	Indicates the file system path to the database file or directory, which is used during the initialization of the database connection. Should be a folder of container path.
DOWNLOAD_PATH	Specifies the directory path where downloaded streams or files are saved. This path is set during the application's initialization process. Should be a folder of container path.
LOGIN_SECRET	A temporary password or secret used for the initial login or setup of a user account during the application's initialization phase. This option has no effect after the initialization for security reasons.
PGID	Group ID
PUID	User ID

Proxy settings

If you are using a proxy, you can set the HTTP_PROXY environment variable in the backend service.

For proxies deployed on the local machine, you can use the following settings:

• Windows and MacOS users:

environment:
  - HTTP_PROXY=http://host.docker.internal:<port>/

• Linux users: Use the output of the following command to get the host IP address:

ip addr show docker0

Then, replace <host_ip> with the IP address and <port> with the port number.

environment:
  - HTTP_PROXY=http://<host_ip>:port/

Frontend environment variables

Environment	Description
NEXTAUTH_URL	Specifies the base URL of the application, typically the root URL of the deployed site, used for authentication callbacks and redirects.
NEXT_PUBLIC_BASE_URL	Defines the public base URL of the application, used as the base path for frontend and API requests.
NEXTAUTH_SECRET	A secret key used to encrypt sessions and authentication tokens, ensuring user data security.
API_URL	The backend connection URL, used to connect to and access the backend service.
WS_API_URL	The backend websocket connection URL, used to retrieve real time event updates.

1.2 Running the Docker compose

Make sure you are in the same directory as the docker-compose.yml file, then run the following command:

docker compose up -d && docker compose logs -f

Now, you are all set! You can access the web interface at http://localhost:15275 and start configuring the tool (see Configuration).

TIP

You can detach from the logs by pressing Ctrl + C. And you can reattach to the logs by running docker compose logs -f. To stop the containers, run docker compose down.

2. Building from source

2.1 Prerequisites

• Internet access, obviously 😂
• Git (Used to get the version information by the backend)
• A java development kit (JDK) (version 21 or later), Amazon Corretto 21 is recommended.
• FFmpeg (Make sure it's in your PATH). No longer required if you are using the kotlin engine.
• FFprobe (Make sure it's in your PATH). Required if Exit on download error option is enabled.
• Streamlink (optional, for recording streams, make sure it's in your PATH)
• Rclone (optional, for uploading to cloud storage, make sure it's in your PATH)
• Sqlite3 (for storing stream, upload information, make sure it's in your PATH)

2.2 Building the backend

To build the project, first clone the repository and navigate to the root directory of the project.

git clone https://github.com/stream-rec/stream-rec.git
cd stream-rec

Then, build the project using the following command:

./gradlew stream-rec:build -x test

The built fat jar file stream-rec.jar will be located in the stream-rec/build/libs directory.

2.2.1 Running the jar file

To run the jar file with default configuration, use the following command:

java -jar stream-rec/build/libs/stream-rec.jar

Several environment variables can be set to configure the tool:

• DB_PATH: Path to the SQLite database folder. (default: ./db)
• JWT_SECRET: Secret key for JWT token generation.
• LOG_LEVEL: Log level (default: info).
• LOGIN_SECRET: Login password for the web interface (default: stream-rec, if not set).

For example:

java -DDB_PATH=/path/to/your/db -DLOG_LEVEL=DEBUG -DJWT_SECRET=SECRET -DLOGIN_SECRET=123 -jar stream-rec/build/libs/stream-rec.jar

IMPORTANT

• Please set the LOGIN_SECRET environment variable to a secure password. This password is used to log in to the web interface.
• This password cannot be changed after the first run.

2.3 Building the frontend

Frontend is used to configure the tool, it's a simple web interface built with React.

Navigate to frontend repository and follow the build instructions.

After that, you can start configuring the tool by accessing the web interface at http://localhost:15275. Take a look at the Configuration page for more information.