[tor-bugs] #20380 [Metrics/CollecTor]: Expand INSTALL.md to a more complete operator's guide

[Tor Bug Tracker & Wiki]

#20380: Expand INSTALL.md to a more complete operator's guide
-------------------------------+---------------------------------
 Reporter:  karsten            |          Owner:
     Type:  enhancement        |         Status:  needs_review
 Priority:  Medium             |      Milestone:  CollecTor 1.1.0
Component:  Metrics/CollecTor  |        Version:
 Severity:  Normal             |     Resolution:
 Keywords:                     |  Actual Points:
Parent ID:                     |         Points:
 Reviewer:                     |        Sponsor:
-------------------------------+---------------------------------

Comment (by karsten):

 Replying to [comment:12 iwakeh]:
 >
 > This looks good!  The new sections make it a lot easier to read (also
 during review :-)

 Glad to hear!

 > A few small things:
 >
 > * [https://gitweb.torproject.org/karsten/metrics-
 db.git/tree/INSTALL.md?h=task-20380&id=eba2e3f714f1d676ff811b60380fff36f74ad5cd#n129
 line 129]: <your-shell-script-data-dir>

 Or let's just create that directory in the script if it doesn't exist.  No
 reason to do this for `ARCHIVEDIR` and not for `TARBALLTARGETDIR`.

 > * [https://gitweb.torproject.org/karsten/metrics-
 db.git/tree/INSTALL.md?h=task-20380&id=eba2e3f714f1d676ff811b60380fff36f74ad5cd#n150
 line 150 and 155]: <your-webapp-dir>

 Fixed.

 > * [https://gitweb.torproject.org/karsten/metrics-
 db.git/tree/INSTALL.md?h=task-20380&id=eba2e3f714f1d676ff811b60380fff36f74ad5cd#n175
 line 175]: <your-log-dir>

 Fixed.

 > * [https://gitweb.torproject.org/karsten/metrics-
 db.git/tree/INSTALL.md?h=task-20380&id=eba2e3f714f1d676ff811b60380fff36f74ad5cd#n180
 line 180]: 'logback.xml' has to be available in the java classpath the
 name shouldn't change.

 Hmm, when I last tested this I only succeeded when renaming the file, but
 now that doesn't work anymore.  What I did was copy
 `src/main/resources/logback.xml` to the working directory and edit the
 `logfile-base` property to `"${LOGBASE}/colector-"`, yet that change gets
 disregarded.  What am I doing wrong?

 >  Maybe also mention that we use 'slf4j-api' throughout.  Thus, your free
 to use the logging framework of your choice, i.e. any other implementation
 of slf4j could be chosen and provided to CollecTor.

 Do you think the average operator will care?  They'd have to provide a
 .jar file with the logging implementation.  Is this our audience?

 > * [https://gitweb.torproject.org/karsten/metrics-
 db.git/tree/INSTALL.md?h=task-20380&id=eba2e3f714f1d676ff811b60380fff36f74ad5cd#n188
 line 188]: Missing option `-DLOGBASE=<your-log-path>`,

 In fact, I left that out on purpose, because it was disregarded in my
 earlier testing.  Same issue as above, what am I doing wrong?

 >  and maybe add 'the -Xmx option is based on 4g RAM here, if your machine
 has more feel free to adapt this as needed'

 Added a line for that.

 > * [https://gitweb.torproject.org/karsten/metrics-
 db.git/tree/INSTALL.md?h=task-20380&id=eba2e3f714f1d676ff811b60380fff36f74ad5cd#n225
 line 225]:  This is still based on the assumption everything lives below
 the workdir, which doesn't need to be the case.  Maybe, change along the
 line 'A backup of your CollecTor instance should include the <ArchivePath>
 and your configuration and other changes, which makes it possible to set-
 up this instance again.  A backup for short term recovery would also
 include the more volatile data in <StatsPath>, <RecentPath, and
 <OutputPath>.' (This suggestion can surely be phrased better.)

 Changed.

 Replying to [comment:13 iwakeh]:
 > Addendum:
 >
 > The shell script can also be anywhere as long a the paths are set
 correctly.

 Changed.

 Please find [https://gitweb.torproject.org/karsten/metrics-
 db.git/log/?h=task-20380-2 my branch task-20380-2] with some changes.  I
 guess the only part that needs fixing before we merge is the logging
 section, plus the things that I overlooked.

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/20380#comment:14>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online