Skip to content
Logchef

Quick Start Guide

This guide will help you get Logchef up and running quickly. We’ll cover installation, basic setup, and how to make your first log query.

Prerequisites

  • Docker (for the recommended setup) or a Linux/macOS system for binary installation
  • A Clickhouse instance (included in Docker setup)
  • SSO Provider (Dex is included in the Docker setup)

Installation Options

The Docker setup is the easiest way to get started with Logchef, as it includes everything you need: Logchef, Clickhouse, Dex SSO, and Vector for demo data.

Terminal window
# Download the compose file
curl -LO https://raw.githubusercontent.com/mr-karan/logchef/refs/heads/main/deployment/docker/docker-compose.yml


# Start the services
docker compose up -d

This will start:

  • Logchef UI and API on port 8125 (accessible at http://localhost:8125)
  • Clickhouse for log storage (ports 8123 and 9000)
  • Dex SSO provider on port 5556
  • Vector for generating demo logs

After starting, you can access the Logchef UI at http://localhost:8125.

Using Pre-built Binaries

For production deployments or running without Docker, you can download pre-built binaries:

Terminal window
# Download the latest release for your platform (example for Linux amd64)
# Check latest version at https://github.com/mr-karan/logchef/releases
curl -L -O https://github.com/mr-karan/logchef/releases/download/v0.2.1/logchef_0.2.1_linux_amd64.tar.gz


# Extract the archive
tar xzf logchef_0.2.1_linux_amd64.tar.gz


# Make the binary executable
chmod +x logchef


# Create a basic configuration file
curl -L -O https://github.com/mr-karan/logchef/raw/main/config.toml


# Edit the config file to match your environment
# You'll need to update the OIDC settings and database path


# Run Logchef with your config
./logchef -config config.toml

Building from Source

If you prefer to build from source:

Terminal window
# Clone the repository
git clone https://github.com/mr-karan/logchef.git
cd logchef


# Build the frontend and backend
just build


# Run with the default config
just run

First Login

  1. After starting Logchef, visit http://localhost:8125 in your browser
  2. You’ll be redirected to the SSO login page
  3. For the Docker setup, use the default credentials:
    • Email: admin@logchef.internal
    • Password: password

Initial Setup

Before you can start querying logs, you need to set up a team, create a data source, and assign the source to your team.

1. Create a Team

  1. Navigate to Access > Teams
  2. Click “Add Team”
  3. Enter a team name (e.g., “Engineering”)
  4. Save the team

2. Add Yourself to the Team

  1. From the Teams page, select your newly created team
  2. Under Team Members, click “Add User”
  3. Add your email address and select appropriate permissions
  4. Save changes

3. Configure a Data Source

  1. Navigate to Sources > Manage Sources
  2. Click “Add Source”
  3. Enter your Clickhouse connection details: 
    Name: Demo Logs
    Host: localhost (or clickhouse if using Docker)
    Port: 9000
    Database: default
    Table: logs

Logchef Source Settings View

  1. Test the connection and save

4. Assign the Source to Your Team

  1. Navigate to Access > Teams
  2. Select your team
  3. Under Data Sources, click “Add Source”
  4. Select the source you created and save

Writing Your First Query

Now you’re ready to explore your logs:

  1. Go to the Explore page
  2. Select your team and data source
  3. Try some example queries:

Basic search:

namespace="syslog"

Filter by severity:

namespace="syslog" and severity_text!="INFO"

Search for specific text in the log body:

namespace="syslog" and body="error"

Next Steps