search

tremor-rs / tremor-www

The source code for the www.tremor.rs website
https://www.tremor.rs/
Apache License 2.0
14 stars 33 forks source link

Possibly wrong version in the tremor installation instructions- errors and potential fix also included #334

Open devskillz47 opened 1 week ago

devskillz47 commented 1 week ago

Problem The current installation instructions (on https://www.tremor.rs/docs/0.12/getting-started/install) point to tremor 0.12.0-rc.2 and although "tremor run server" seems to work not all associated libraries seem to have been included which make at least the demo scenarios unrunnable (ie. error message: "Module tremor::connectors not found or not readable error")

Steps

  1. $ wget https://github.com/tremor-rs/tremor-runtime/releases/download/v0.12.0-rc.2/tremor_0.12.0-rc.2_amd64.deb
  2. $ sudo apt install libatomic1
  3. $ sudo dpkg -i tremor_0.12.0-rc.2_amd64.deb
  4. running the basic demo scenario from (https://www.tremor.rs/docs/0.12/guides/basics):
    • tremor run passthrough/main.troy will fail with the above mentioned error (ie. Module tremor::connectors not found or not readable error)

Possible Solution(s)

  1. change the installation instructions to download and install the 0.12.0 library version:
  2. $ sudo apt install libatomic1
  3. $ sudo dpkg -i tremor_0.12.0_amd64.deb

Notes

  1. The 0.12.0 tremor version will install correctly both using dpkg and by unpacking the .tar.gz library(tremor-0.12.0-x86_64-unknown-linux-gnu.tar.gz) and running "tremor" from within the folder
  2. The 0.12.4 tremor version will install correctly using dpkg but unfortunately, the packaged version (tremor-0.12.4-x86_64-unknown-linux-gnu.tar.gz) is missing some dependencies or configuration and won't work correctly.
  3. No executable or packaged library was found which would work directly in windows although the above commands do work in WSL

Output of rustup --version: rustup 1.27.1 (54dd3d00f 2024-04-24) info: This is the version for the rustup toolchain manager, not the rustc compiler. info: The currently active rustc version is rustc 1.81.0 (eeb90cda1 2024-09-04)

Output of rustup show: Default host: x86_64-unknown-linux-gnu rustup home: /home/devskillz47/.rustup stable-x86_64-unknown-linux-gnu (default) rustc 1.81.0 (eeb90cda1 2024-09-04)

Output of tremor --version: tremor 0.12.0

Screenshot_2024-10-03_180302 Screenshot_2024-10-03_200221

darach commented 1 week ago

Hi @devskillz47,

Well spotted and thank you for reporting - this is a indeed documentation bug.

In the edge versions we should always refer to the latest version. We currently refer to a 0.12 release candidate.

In published versioned docs, we should refer to the version relevant for that published version. This is also broken and not referring to the latest version in that release.

TL;DR We don't have automation around that so human error creeps in - and it tripped you up! Apologies!

A lot can change in tremor between release candidates and a release.

In rc.2 for example, it should actually be importing troy::connectors. Here's what I get with the docker image which is a quick way of getting to a specific version:

 docker run -it --entrypoint=/bin/bash tremorproject/tremor:0.12.0-rc.2
Unable to find image 'tremorproject/tremor:0.12.0-rc.2' locally
0.12.0-rc.2: Pulling from tremorproject/tremor
1fe172e4850f: Pull complete
0f7a09356ab2: Pull complete
9ed9fd0da9cf: Pull complete
9f2b1af0c7af: Pull complete
f369d1d5546c: Pull complete
0a2e9637503d: Pull complete
773923c4a5cb: Pull complete
04d0ceeebaee: Pull complete
4ad7c67c1aed: Pull complete
5c80e7df2a62: Pull complete
Digest: sha256:54bae6b1f64c030086bbc1b083daedc8c5d1725093e76b1571744e1fa26505be
Status: Downloaded newer image for tremorproject/tremor:0.12.0-rc.2
root@b35f93c5d432:/# which tremor
root@b35f93c5d432:/# echo $TREMOR_PATH
/usr/local/share/tremor:/usr/share/tremor/lib
root@b35f93c5d432:/# cd /etc/tremor/
root@b35f93c5d432:/etc/tremor# ls
config  logger.yaml
root@b35f93c5d432:/etc/tremor# ls config
docker.troy
root@b35f93c5d432:/etc/tremor# /tremor run config/docker.troy
{"onramp":"metronome","ingest_ns":1732106045142393814,"id":0,"hostname":"b35f93c5d432"}
{"onramp":"metronome","ingest_ns":1732106046142596015,"id":1,"hostname":"b35f93c5d432"}
^C

And the interesting part:

 cat config/docker.troy
define flow docker
flow
    use troy::connectors; # Notice the different module namespace
    use troy::pipelines;
    use std::time::nanos;

Fixes in the docs would be of the form:

devskillz47 commented 1 week ago

For fixing the documentation, I think we could use the 2nd option you mentioned- fixing the versioned docs so that each major refers to its latest minor/patch release. From a stability point of view, the latest minor/patch release of a major should always be correct and working so there shouldn't be any problems. From an automation point of view, I am not sure. A rolling latest could be the easiest solution but I'll also have a look around maybe I can find some info on how other software projects have solved the problem (ie. java, scala, python, etc)