Skip to main content

LogStreamr Installation

Before You Begin​

System Requirements​

  • Linux x86-64
  • Kernel 3.10+
  • systemd
Linux Distribution Compatibility

LogStreamr should be compatible with any modern and widely-supported Linux distribution.
It has been successfully tested on:

  • Ubuntu 20.04+
  • Debian 11
  • RHEL 8+
  • Arch

StreamStack makes no guarantee of compatibility with systems outside of this list.

Prerequisites​

  • curl (for basic installation)
  • git (for advanced installation)
  • Go 1.20+ (for advanced installation)

Installation Methods​

LogStreamr can be installed on Linux systems either with a pre-built binary and a provided installation script (basic installation), or by building the binary directly from the source code (advanced installation).
For the vast majority of users, it is recommended to use the basic installation method.

Please note that the installation method (basic or advanced) does not impact the software once installed.

Basic Installation​

Install Prerequisites​

If you haven't already, install the prerequisites for the basic installation method (curl).

sudo apt install -y curl

Download and Extract Installation Files​

Download the release v0.1.0 files using curl.

curl -o logstreamr.tar.gz https://github.com/streamstack/logstreamr/releases/download/v0.1.0/logstreamr-v0.1.0-linux-x86_64.tar.gz

Now, extract the downloaded installation files.

tar -xvcf logstreamr.tar.gz

Run the Installer​

To complete the installation, navigate to the extracted folder and run the install.sh script.

cd logstreamr-v0.1.0-linux-x86_64
sudo ./install.sh

Verify the Installation​

Now that installation has completed, double-check that LogStreamr is properly installed by running:

logstreamr --version

You should see:

logstreamr v0.1.0 (build 3e29f0a) linux/amd64
Built with Go 1.20.6 on 2024-04-04

Congratulations! You have successfully installed LogStreamr. Now continue to the Configuration Guide to set up your installation.

Advanced Installation​

Install Prerequisites​

If you haven't already, install the prerequisites for the advanced installation method (git and go).

To properly install the latest version of Go, follow the documentation here (https://go.dev/doc/install).

sudo apt install -y git

Clone Source Code​

Clone the latest source code from the LogStreamr GitHub repository.

git clone https://github.com/streamstack/logstreamr.git
cd logstreamr

Build Binary​

Build the LogStreamr binary using Go (make sure you're in the logstreamr directory):

go build

Install the binary​

Copy the newly created binary to the /usr/local/bin directory.

sudo install -m 0755 logstreamr /usr/local/bin/logstreamr

Create and Populate the Configuration Folder​

Once the binary is installed, create the configuration folder at /etc/logstreamr and copy the sample configuration file to it.

sudo mkdir -p /etc/logstreamr
sudo cp logstreamr.yml.example /etc/logstreamr/logstreamr.yml

Create and Enable the systemd Service​

Finally, copy the provided logstreamr.service file to /etc/systemd/system and enable it to complete the installation.

sudo cp logstreamr.service /etc/systemd/system/logstreamr.service
sudo systemctl daemon-reexec
sudo systemctl enable --now logstreamr

Verify the Installation​

Now that installation has completed, double-check that LogStreamr is properly installed by running:

logstreamr --version

You should see:

logstreamr v0.1.0
note

The --version output for the advanced installation is shorter as it does not include the specific build information that the basic installation does.

Congratulations! You have successfully installed LogStreamr. Now continue to the Configuration Guide to set up your installation.

Troubleshooting​

Permission denied errors​

Ensure that all commands targeting write-protected directories are run by root or using the sudo command.
These commands include:

  • sudo ./install.sh
  • sudo install -m 0755 logstreamr /usr/local/bin/logstreamr
  • sudo mkdir -p /etc/logstreamr
  • sudo cp logstreamr.yml.example /etc/logstreamr/logstreamr.yml
  • sudo cp logstreamr.service /etc/systemd/system/logstreamr.service
  • sudo systemctl daemon-reexec
  • sudo systemctl enable --now logstreamr

Compile Errors​

Compile errors could mean that your version of Go is outdated. Ensure your version of Go is >=1.20.

If the compile issues persist, you may try using make build instead of go build in the source directory.
Note: The binary file will be placed in the bin subdirectory, the configuration file in the examples subdirectory, and the systemd file in the systemd subdirectory.

note

To use make build you must have make installed on your system.

systemd Errors / Service not running​

First, ensure systemd is installed on the system.

If it is, make sure that logstreamr.service is copied to /etc/systemd/system and the daemon is reloaded with sudo systemctl daemon-reexec before running sudo systemctl enable logstreamr.

Existing config folder​

If reinstalling LogStreamr, make sure that /etc/logstreamr is fully removed before attempting to re-run the installation script, as it will not overwrite the directory if it exists.