Install

The first step in using Logmunch is to install it, somewhere.

You're Going To Need a Secret Key

The rest of this process isn't going to work unless you have a secret key. It's necessary for authentication in logmunch to work.

Generate it like this:

$> openssl rand -base64 32

This will generate a value that looks like:

XVH72iQN0WETdbWJG+bglNoW/eo/8tCTa7iesC6f16w=

Save the value for later!

Docker

On any computer already running docker, you can get started with a simple command:

$> docker run -d \
        --name=logmunch \
        --restart=always \
        --volume=/tmp/data:/tmp/data
        --p 1234:1234
		--env "LOGMUNCH_DEFAULT_PASSWORD=hunter2" \
        --env "ROCKET_SECRET_KEY=XVH72iQN0WETdbWJG+bglNoW/eo/8tCTa7iesC6f16w=" \
        --env "ROCKET_PORT=1234" \
        --env "ROCKET_ADDRESS=0.0.0.0" \
        --env "LOGMUNCH_WRITE_TOKEN=ZoSPvJcP46xUTSJxmXz69B..." \
        --env "LOGMUNCH_RAM_GB=7.8" \
        --env "LOGMUNCH_DISK_GB=150" \
        --env "LOGMUNCH_DATA_DIRECTORY=/tmp/data" \
        --env "LOGMUNCH_MAX_WRITE_THREADS=8" \
        logmunch\logmunch_x86

Wait, though! All of these environment values are set wrong, you should read more about the Arguments, below!

But What If I'm Running on ARM, not X86?

Oho, there's a trick to that:

$> docker run -d \
        --name=logmunch \
        --restart=always \
        --volume=/tmp/data:/tmp/data
        --p 1234:1234
		--env "LOGMUNCH_DEFAULT_PASSWORD=hunter2" \
        --env "ROCKET_SECRET_KEY=XVH72iQN0WETdbWJG+bglNoW/eo/8tCTa7iesC6f16w=" \
        --env "ROCKET_PORT=1234" \
        --env "ROCKET_ADDRESS=0.0.0.0" \
        --env "LOGMUNCH_WRITE_TOKEN=ZoSPvJcP46xUTSJxmXz69B..." \
        --env "LOGMUNCH_RAM_GB=7.8" \
        --env "LOGMUNCH_DISK_GB=150" \
        --env "LOGMUNCH_DATA_DIRECTORY=/tmp/data" \
        --env "LOGMUNCH_MAX_WRITE_THREADS=8" \
        logmunch\logmunch_arm

That's right, logmunch\logmunch_arm instead of logmunch\logmunch_x86.

Unfortunately: as soon as you shut down the window, Logmunch will go down with it. In order to keep Logmunch running, you need to engage the services of some kind of supervisor. If you're running Ubuntu, you could, for example, use systemd.

systemd

Let's imagine you're root on a freshly created Ubuntu box.

We've placed the logmunch binary at /root/logmunch, and run chmod a+x /root/logmunch to make it executable.

Create /root/logenv:

LOGMUNCH_DEFAULT_PASSWORD=hunter2
ROCKET_SECRET_KEY=XVH72iQN0WETdbWJG+bglNoW/eo/8tCTa7iesC6f16w=
ROCKET_PORT=80
ROCKET_ADDRESS=0.0.0.0
LOGMUNCH_WRITE_TOKEN=ZoSPvJcP46xUTSJxmXz69B
LOGMUNCH_RAM_GB=1.8
LOGMUNCH_DISK_GB=18
LOGMUNCH_DATA_DIRECTORY=/tmp/data
LOGMUNCH_MAX_WRITE_THREADS=2

(making sure, of course, to replace the environment variables with sensible values)

Create /etc/systemd/system/logmunch.service:

[Unit]
Description=Logmunch
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=3
User=root
EnvironmentFile=/root/logenv
ExecStart=/root/logmunch

[Install]
WantedBy=multi-user.target

Now, run systemctl start logmunch to kick off logmunch.

systemctl status logmunch and journalctl -u logmunch.service -n 100 should demonstrate that logmunch has successfully booted.

Once that's working, systemctl enable logmunch will ensure that logmunch starts on boot.

Kubernetes

idk man, ¯\_(ツ)_/¯

Arguments

At a minimum you should be setting a LOGMUNCH_DEFAULT_PASSWORD, tossing some high-quality garbage into the ROCKET_SECRET_KEY and LOGMUNCH_WRITE_TOKEN, and figuring out your RAM, Disk, and CPU numbers for LOGMUNCH_RAM_GB and LOGMUNCH_DISK_GB and LOGMUNCH_MAX_WRITE_THREADS.

To be honest, you'll probably need to set a lot of these guys manually.

LOGMUNCH_DEFAULT_PASSWORD: (default: admin) - the password to log in and ... see all the logs. For the love of god, set this to something.
ROCKET_SECRET_KEY: (default: None) - generate a key with ` and put it in here. Why?
ROCKET_PORT: (default: 8000) - the port that Logmunch is going to run on
ROCKET_ADDRESS: (default: 127.0.0.1) - the IP address to serve Logmunch from. Set to 0.0.0.0 if you want to serve all comers.
LOGMUNCH_WRITE_TOKEN : (default: null) - this is an authorization token that must be sent with all logs, or your Logmunch server will automatically discard those logs. You'll need to remember this when you're building a system to send logs to Logmunch, later on.
LOGMUNCH_RAM_GB: (default: 1.8) - how many gigabytes of RAM are set aside for Logmunch. (Remember: leave a little for the underlying OS!)
LOGMUNCH_DISK_GB: (default: 18) - how many gigabytes of disk space are set aside for Logmunch. (Remember: leave a little for the underlying OS!)
LOGMUNCH_DATA_DIRECTORY: (default: ./data/) - where the logs are kept. (The /tmp/logs?)
LOGMUNCH_MAX_WRITE_THREADS: (default: 2) - how many threads can devote themselves to writing logs. (If you have a computer with 4VCPUs, set this to 4?)
LOGMUNCH_LICENSE_KEY: (default: null) - set this to a valid license key to indicate that you've purchased Logmunch, for money.
ROCKET_ENV: (default: production) - leave this set to "production"

example:

(note: this license key looks valid, but it's not a real license key)

$>  LOGMUNCH_DEFAULT_PASSWORD=hunter2 \
    ROCKET_SECRET_KEY=NQ81myfpRf9YIiWZjAuUtO9OQx4iu3ByEiyNFSHKU2SioTv3JeOZUyZPWzSeNysP \
    ROCKET_PORT=1234 \
    ROCKET_ADDRESS=0.0.0.0 \
    LOGMUNCH_WRITE_TOKEN=ZoSPvJcP46xUTSJxmXz69Bi1L4OkBNr3DPChF1B4XdgNI6DMi7AL8NrcN3geDLXr \
    LOGMUNCH_RAM_GB=7.8 \
    LOGMUNCH_DISK_GB=150 \
    LOGMUNCH_DATA_DIRECTORY=/tmp/logmunch
    LOGMUNCH_MAX_WRITE_THREADS=8 \
    LOGMUNCH_LICENSE_KEY=logmunchabunchacruncha-018fa82f-700d-790c-a9c2-45fb6bc60c07-----yIKqtUSmdV4TEQanSrRi/a8ksuVQR4+vphJHoRcozAfFlOgx3md5C+ZNi9xCX1vWYIqF8Hw7WncLD7Nbmx6rDw== \
        logmunch

Careful About That Password

The password test is not meaningfully rate limited, so if you're running a production system, pick a long, unique stream of random data. Maybe generate one of those random openSSL strings like you did with the secret key, and store that in a password manager.

Don't Keep Important Data in /tmp

All of the examples here use /tmp/data as the example storage location for data.

Thing about /tmp is that the data in there is often cleared on system reboot. Which you probably don't want? Maybe create a directory somewhere else.

I've Installed It: Now What?

Open up a browser and visit logmunch at yourserver.tld:1234!

You should be able to log in with the LOGMUNCH_DEFAULT_PASSWORD that you set, at which point you're ... looking at... no logs!

It's time to point some logs at Logmunch!

Logmunch 2.1.0