Installation

Three ways to run SIEMLite: a prebuilt binary (or built from source), a systemd service installed with one command, or Docker. Any can run on the internet with a Let's Encrypt certificate. The web UI is built into the binary, so there is nothing else to install.

Run the binary

Download a prebuilt binary for Linux, macOS or Windows (x86-64 or ARM64) from the latest release, check it against SHA256SUMS, unpack it and run ./siemlite. Or build it yourself (requires Go):

git clone https://github.com/justwaters/SIEMLite.git
cd SIEMLite
go build -o siemlite .
./siemlite

On first start SIEMLite creates siemlite.db (users, sources, rules, alerts and settings) and a siemlite-events folder for the events, generates siemlite.crt / siemlite.key, and creates an admin user with a random password that is printed once. Copy it. Open https://localhost:8443 and sign in; your browser will warn about the self-signed certificate unless you trust siemlite.crt or supply your own with -tls-cert / -tls-key.

Nothing to look at yet? Run the log generator next to it, which SIEMLite sets up on first start: loggen -eps 10 sends ten realistic test events a second, attacks included. See Test logs.

Install as a service (Linux)

On Ubuntu or any other systemd Linux server, SIEMLite installs itself. Download the release for your machine (or build it), then run it with the install subcommand as root:

sudo ./siemlite install --dry-run   # print what it would do, change nothing
sudo ./siemlite install             # install, or update an existing install

It is a subcommand, not something the program does by itself, so running ./siemlite to try it never touches the system. The installer:

Copies the program to /usr/local/bin/siemlite (root-owned, replaced atomically).
Creates the siemlite system user (no login, no home) and /var/lib/siemlite (mode 0700, owned by that user) for the database, certificate and backups.
Writes /etc/siemlite/siemlite.env from the defaults: HTTPS on 0.0.0.0:8443 and syslog on UDP and TCP 514 (--no-syslog leaves syslog off). Settings are SIEMLITE_<FLAG>=value lines, as in Options.
Writes the hardened siemlite.service (NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp, Restart=on-failure; the one capability, binding ports below 1024, is granted only while the settings listen on one).
Creates the admin account and prints its password once, on your terminal (it does not go to the journal), then runs systemctl daemon-reload, enable and start.

The service runs as an unprivileged user, so the Security audit checks for that and for file permissions pass.

Updating: download the new release and run sudo ./siemlite install again. It replaces the program atomically, restarts the service and says what changed (program: v0.27 -> v0.28). It keeps the data, never overwrites siemlite.env, and rewrites the unit only if you haven't edited it; if you have, yours is kept and the new one is saved as siemlite.service.new to compare. Put changes to the unit in a drop-in (systemctl edit siemlite) so updates can refresh the rest. It refuses to go back to an older version unless you add --allow-downgrade.

Removing: sudo siemlite install --uninstall removes the service and program and keeps the data, settings and user; add --purge to delete those too. --dry-run works with both.

It refuses, changing nothing and exiting non-zero, when it isn't run as root, the OS isn't Linux, systemd isn't running, or it is inside a container (use Docker there).

How this relates to the other ways to update. Docker has its own path (./update.sh) and the installer won't run in a container, so they never meet. The System page's Update and restart button cannot replace the program of a service installed this way, on purpose: the program is root-owned and the service can't write to it, so a flaw in SIEMLite can't swap the program that an admin later runs with sudo. The card says it can't write to /usr/local/bin; update with sudo ./siemlite install instead. The System page still tells you when a release is out.

Run with Docker

The web UI is built into the binary, so this is a single container. Every release is published as an image for x86-64 and ARM64: set SIEMLITE_IMAGE=ghcr.io/justwaters/siemlite:v0.28.2 in .env to use it, or leave it out to build from the checkout. Either way, start and update with ./update.sh:

git clone https://github.com/justwaters/SIEMLite.git && cd SIEMLite
cp .env.example .env        # optional: ports, certificate names, GeoIP, feeds, retention
./update.sh                 # starts SIEMLite; run it again to update
docker compose logs siemlite | grep -A1 'username: admin'   # the admin password, printed on first start

./update.sh gets the newest release (moving SIEMLITE_IMAGE in .env to it) or, when built from the checkout, runs git pull and rebuilds; then it restarts SIEMLite, says which version it went from and to, and waits until it is healthy:

Downloading SIEMLite v0.19.1...
Updating SIEMLite v0.19 -> v0.19.1
SIEMLite v0.19.1 is up.

./update.sh v0.19 picks a particular release. Going back to an older one warns that the database may have been changed by the newer version, and asks first. docker compose pull && docker compose up -d (or docker compose up -d --build) still works too; it just doesn't say what changed.

The password is printed only by the first container. Rebuilding replaces the container and its logs, so if you missed it, set a new one: docker compose exec siemlite siemlite users passwd -username admin.

The database and certificate live in the siemlite-data volume, so rebuilds and upgrades keep every event, account and key. docker compose down keeps the volume; docker compose down -v deletes it.
Ports: HTTPS on 8443, syslog on 514 (UDP and TCP) and syslog over TLS on 6514. Change the host ports in .env. The local port, 8444, is published on 127.0.0.1 only, so only the server itself reaches it (see Sign-in restrictions).
Settings: every server flag can be set in .env as SIEMLITE_<FLAG>, e.g. SIEMLITE_SYSLOG_ALLOW=10.0.0.0/8 for -syslog-allow. .env.example lists the useful ones.
Set SIEMLITE_TLS_HOSTS to the names or IPs people use to reach the server before the first start: the certificate is generated once. To regenerate it later, delete it from the volume and restart (the image has no shell, so use a throwaway container; the volume is named after the checkout folder): docker run --rm -v siemlite_siemlite-data:/data alpine rm /data/siemlite.crt /data/siemlite.key && docker compose restart. To trust the certificate on a client, copy it out with docker compose cp siemlite:/data/siemlite.crt ..
GeoIP: put the .mmdb files in ./geoip/ and set SIEMLITE_GEOIP_CITY=/geoip/GeoLite2-City.mmdb (and _ASN).
Management commands run inside the container: docker compose exec siemlite siemlite users create -username alice -role standard, and the same for keys and intel. To import a feed file, pipe it in: docker compose exec -T siemlite siemlite intel import -source x -file - < iocs.txt.
Syslog senders keep their real IP through Docker's port mapping, so -syslog-allow works. The exception is a sender on the Docker host itself, which appears as the Docker network's gateway address.
The image is about 25 MB, has no shell, and runs as an unprivileged user. Docker restarts it if /health stops answering.

Run on the internet

To serve SIEMLite on a public domain with a trusted certificate from Let's Encrypt, see Run on the internet.

Upgrading

SIEMLite upgrades its database automatically on first start. On the System page you can update in place, for a plain binary and for Docker. You can also pull or rebuild the image: docker compose pull && docker compose up -d, or git pull && docker compose up -d --build. Notes for each older version:

From v0.8

Each day file is upgraded once, when the server (or a command) first opens it: the stored line becomes the event's message and the search index is rebuilt over the parsed event, which can take a little while on a large history. Original lines from before the upgrade are removed about 24 hours later, like any other. Backups made before the upgrade can still be restored; backups made after it can't be restored by 0.8.

From v0.7 or earlier

Sample data is gone: its events, alerts and source are deleted, and the log generator takes its place. Events move from siemlite.db into one file per day in the background after the first start (the log shows progress, and a restart resumes where it stopped). Search, the dashboard and alerts work throughout. When it finishes, siemlite.db shrinks to just users, sources, rules, alerts and settings. Make a backup first if you like; backups made by 0.8 can't be restored by 0.7.

From v0.4

The database is upgraded automatically and keeps every event. API keys become access token sources and keep working; analysts become Standard users who can see every source. Everyone is signed out once during the upgrade. Events stored before it have no source except sample data.

From v0.2

The database is upgraded automatically on first start and keeps every event. Events stored before the upgrade have no source, host or enrichment.

From v0.1

Read and admin API keys no longer exist and are revoked on first start. Sign in with the admin account created for you (or create users with siemlite users create). Write keys keep working.