lixen/logwisp

SHA256

Fork 0

Files

Lixen Wraith 5936f82970 v0.1.11 configurable logging added, minor refactoring, orgnized docs added

2025-07-10 01:17:06 -04:00

11 KiB

Raw Blame History

Installation Guide

This guide covers installing LogWisp on various platforms and deployment scenarios.

Requirements

System Requirements

OS: Linux, macOS, FreeBSD, Windows (with WSL)
Architecture: amd64, arm64
Memory: 64MB minimum, 256MB recommended
Disk: 10MB for binary, plus log storage
Go: 1.23+ (for building from source)

Runtime Dependencies

LogWisp is a single static binary with no runtime dependencies. It only requires:

Read access to monitored log files
Network access for serving streams
Write access for operational logs (optional)

Installation Methods

Pre-built Binaries

Download the latest release:

# Linux (amd64)
wget https://github.com/yourusername/logwisp/releases/latest/download/logwisp-linux-amd64
chmod +x logwisp-linux-amd64
sudo mv logwisp-linux-amd64 /usr/local/bin/logwisp

# macOS (Intel)
wget https://github.com/yourusername/logwisp/releases/latest/download/logwisp-darwin-amd64
chmod +x logwisp-darwin-amd64
sudo mv logwisp-darwin-amd64 /usr/local/bin/logwisp

# macOS (Apple Silicon)
wget https://github.com/yourusername/logwisp/releases/latest/download/logwisp-darwin-arm64
chmod +x logwisp-darwin-arm64
sudo mv logwisp-darwin-arm64 /usr/local/bin/logwisp

Verify installation:

logwisp --version

From Source

Build from source code:

# Clone repository
git clone https://github.com/yourusername/logwisp.git
cd logwisp

# Build
make build

# Install
sudo make install

# Or install to custom location
make install PREFIX=/opt/logwisp

Using Go Install

Install directly with Go:

go install github.com/yourusername/logwisp/src/cmd/logwisp@latest

Note: This installs to $GOPATH/bin (usually ~/go/bin)

Docker

Official Docker image:

# Pull image
docker pull yourusername/logwisp:latest

# Run with volume mount
docker run -d \
  --name logwisp \
  -p 8080:8080 \
  -v /var/log:/logs:ro \
  -v $PWD/config.toml:/config/logwisp.toml:ro \
  yourusername/logwisp:latest \
  --config /config/logwisp.toml

Build your own image:

FROM golang:1.23-alpine AS builder
WORKDIR /build
COPY . .
RUN go build -o logwisp ./src/cmd/logwisp

FROM alpine:latest
RUN apk --no-cache add ca-certificates
COPY --from=builder /build/logwisp /usr/local/bin/
ENTRYPOINT ["logwisp"]

Platform-Specific Instructions

Linux

Debian/Ubuntu

Create package (planned):

# Future feature
sudo apt install logwisp

Manual installation:

# Download binary
wget https://github.com/yourusername/logwisp/releases/latest/download/logwisp-linux-amd64 -O logwisp
chmod +x logwisp
sudo mv logwisp /usr/local/bin/

# Create config directory
sudo mkdir -p /etc/logwisp
sudo cp config/logwisp.toml.example /etc/logwisp/logwisp.toml

# Create systemd service
sudo tee /etc/systemd/system/logwisp.service << EOF
[Unit]
Description=LogWisp Log Monitoring Service
After=network.target

[Service]
Type=simple
User=logwisp
Group=logwisp
ExecStart=/usr/local/bin/logwisp --config /etc/logwisp/logwisp.toml
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
SyslogIdentifier=logwisp

# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadOnlyPaths=/var/log
ReadWritePaths=/var/log/logwisp

[Install]
WantedBy=multi-user.target
EOF

# Create user
sudo useradd -r -s /bin/false logwisp

# Create log directory
sudo mkdir -p /var/log/logwisp
sudo chown logwisp:logwisp /var/log/logwisp

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable logwisp
sudo systemctl start logwisp

Red Hat/CentOS/Fedora

# Similar to Debian, but use:
sudo yum install wget  # or dnf on newer versions

# SELinux context (if enabled)
sudo semanage fcontext -a -t bin_t /usr/local/bin/logwisp
sudo restorecon -v /usr/local/bin/logwisp

Arch Linux

AUR package (community maintained):

# Future feature
yay -S logwisp

macOS

Homebrew

Formula (planned):

# Future feature
brew install logwisp

Manual Installation

# Download and install
curl -L https://github.com/yourusername/logwisp/releases/latest/download/logwisp-darwin-$(uname -m) -o logwisp
chmod +x logwisp
sudo mv logwisp /usr/local/bin/

# Create LaunchDaemon
sudo tee /Library/LaunchDaemons/com.logwisp.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.logwisp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/logwisp</string>
        <string>--config</string>
        <string>/usr/local/etc/logwisp/logwisp.toml</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/logwisp.log</string>
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/logwisp.error.log</string>
</dict>
</plist>
EOF

# Load service
sudo launchctl load /Library/LaunchDaemons/com.logwisp.plist

FreeBSD

Ports

# Future feature
cd /usr/ports/sysutils/logwisp
make install clean

Manual Installation

# Download
fetch https://github.com/yourusername/logwisp/releases/latest/download/logwisp-freebsd-amd64
chmod +x logwisp-freebsd-amd64
mv logwisp-freebsd-amd64 /usr/local/bin/logwisp

# RC script
cat > /usr/local/etc/rc.d/logwisp << 'EOF'
#!/bin/sh

# PROVIDE: logwisp
# REQUIRE: DAEMON
# KEYWORD: shutdown

. /etc/rc.subr

name="logwisp"
rcvar="${name}_enable"
command="/usr/local/bin/logwisp"
command_args="--config /usr/local/etc/logwisp/logwisp.toml"
pidfile="/var/run/${name}.pid"

load_rc_config $name
: ${logwisp_enable:="NO"}

run_rc_command "$1"
EOF

chmod +x /usr/local/etc/rc.d/logwisp

# Enable
sysrc logwisp_enable="YES"
service logwisp start

Windows

Windows Subsystem for Linux (WSL)

# Inside WSL, follow Linux instructions
wget https://github.com/yourusername/logwisp/releases/latest/download/logwisp-linux-amd64
chmod +x logwisp-linux-amd64
./logwisp-linux-amd64

Native Windows (planned)

Future support for native Windows service.

Container Deployment

Docker Compose

version: '3.8'

services:
  logwisp:
    image: yourusername/logwisp:latest
    container_name: logwisp
    restart: unless-stopped
    ports:
      - "8080:8080"
      - "9090:9090"  # If using TCP
    volumes:
      - /var/log:/logs:ro
      - ./logwisp.toml:/config/logwisp.toml:ro
    command: ["--config", "/config/logwisp.toml"]
    environment:
      - LOGWISP_LOGGING_LEVEL=info
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/status"]
      interval: 30s
      timeout: 3s
      retries: 3

Kubernetes

Deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: logwisp
  labels:
    app: logwisp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: logwisp
  template:
    metadata:
      labels:
        app: logwisp
    spec:
      containers:
      - name: logwisp
        image: yourusername/logwisp:latest
        args:
          - --config
          - /config/logwisp.toml
        ports:
        - containerPort: 8080
          name: http
        - containerPort: 9090
          name: tcp
        volumeMounts:
        - name: logs
          mountPath: /logs
          readOnly: true
        - name: config
          mountPath: /config
        livenessProbe:
          httpGet:
            path: /status
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /status
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      volumes:
      - name: logs
        hostPath:
          path: /var/log
      - name: config
        configMap:
          name: logwisp-config
---
apiVersion: v1
kind: Service
metadata:
  name: logwisp
spec:
  selector:
    app: logwisp
  ports:
  - name: http
    port: 8080
    targetPort: 8080
  - name: tcp
    port: 9090
    targetPort: 9090
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: logwisp-config
data:
  logwisp.toml: |
    [[streams]]
    name = "k8s"
    [streams.monitor]
    targets = [{ path = "/logs", pattern = "*.log" }]
    [streams.httpserver]
    enabled = true
    port = 8080

Post-Installation

Verify Installation

Check version:
```
logwisp --version
```

Test configuration:

logwisp --config /etc/logwisp/logwisp.toml --log-level debug

Check service status:

# systemd
sudo systemctl status logwisp

# macOS
sudo launchctl list | grep logwisp

# FreeBSD
service logwisp status

Test streaming:
```
curl -N http://localhost:8080/stream
```

Security Hardening

Create dedicated user:

sudo useradd -r -s /bin/false -d /var/lib/logwisp logwisp

Set file permissions:

sudo chown root:root /usr/local/bin/logwisp
sudo chmod 755 /usr/local/bin/logwisp
sudo chown -R logwisp:logwisp /etc/logwisp
sudo chmod 640 /etc/logwisp/logwisp.toml

Configure firewall:

# UFW
sudo ufw allow 8080/tcp comment "LogWisp HTTP"

# firewalld
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

Enable SELinux/AppArmor (if applicable)

Initial Configuration

Copy example configuration:

sudo cp /usr/local/share/logwisp/examples/logwisp.toml.example /etc/logwisp/logwisp.toml

Edit configuration:
```
sudo nano /etc/logwisp/logwisp.toml
```

Set up log monitoring:

[[streams]]
name = "myapp"
[streams.monitor]
targets = [
    { path = "/var/log/myapp", pattern = "*.log" }
]

Restart service:
```
sudo systemctl restart logwisp
```

Uninstallation

Linux

# Stop service
sudo systemctl stop logwisp
sudo systemctl disable logwisp

# Remove files
sudo rm /usr/local/bin/logwisp
sudo rm /etc/systemd/system/logwisp.service
sudo rm -rf /etc/logwisp
sudo rm -rf /var/log/logwisp

# Remove user
sudo userdel logwisp

macOS

# Stop service
sudo launchctl unload /Library/LaunchDaemons/com.logwisp.plist

# Remove files
sudo rm /usr/local/bin/logwisp
sudo rm /Library/LaunchDaemons/com.logwisp.plist
sudo rm -rf /usr/local/etc/logwisp

Docker

docker stop logwisp
docker rm logwisp
docker rmi yourusername/logwisp:latest

Troubleshooting Installation

Permission Denied

If you get permission errors:

# Check file ownership
ls -la /usr/local/bin/logwisp

# Fix permissions
sudo chmod +x /usr/local/bin/logwisp

# Check log directory
sudo mkdir -p /var/log/logwisp
sudo chown logwisp:logwisp /var/log/logwisp

Service Won't Start

Check logs:

# systemd
sudo journalctl -u logwisp -f

# Manual run
sudo -u logwisp /usr/local/bin/logwisp --config /etc/logwisp/logwisp.toml

Port Already in Use

Find conflicting process:

sudo lsof -i :8080
# or
sudo netstat -tlnp | grep 8080

11 KiB Raw Blame History

Installation Guide

Requirements

System Requirements

Runtime Dependencies

Installation Methods

Pre-built Binaries

From Source

Using Go Install

Docker

Platform-Specific Instructions

Linux

Debian/Ubuntu

Red Hat/CentOS/Fedora

Arch Linux

macOS

Homebrew

Manual Installation

FreeBSD

Ports

Manual Installation

Windows

Windows Subsystem for Linux (WSL)

Native Windows (planned)

Container Deployment

Docker Compose

Kubernetes

Post-Installation

Verify Installation

Security Hardening

Initial Configuration

Uninstallation

Linux

macOS

Docker

Troubleshooting Installation

Permission Denied

Service Won't Start

Port Already in Use

See Also

11 KiB

Raw Blame History