Quick Start

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 or VictoriaLogs instance (ClickHouse is included in the Docker setup)
• SSO Provider (Dex is included in the Docker setup)

Installation Options

Using Docker (Recommended)

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.

# 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.

The compose file demonstrates the ClickHouse path. The VictoriaLogs tutorial includes a one-command local VictoriaLogs server and a JSON-line ingestion example if you want to try the new datasource alongside it.

Using Pre-built Binaries

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

# Grab the latest version tag from https://github.com/mr-karan/logchef/releases/latest (e.g. 2.0.0), set it once, then download:
VERSION="2.0.0"

# Download the release for your platform (example for Linux amd64)
curl -L -O https://github.com/mr-karan/logchef/releases/download/v${VERSION}/logchef_${VERSION}_linux_amd64.tar.gz

# Extract the archive
tar xzf logchef_${VERSION}_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. The quickest path is
# built-in email + password login: enable [auth.local] and set a bootstrap
# admin. No external identity provider needed. OIDC/SSO is optional.
#
#   [auth.local]
#   enabled = true
#   admin_email = "admin@example.com"
#   # supply the password via env instead of the file:
#   # export LOGCHEF_AUTH__LOCAL__ADMIN_PASSWORD="a-strong-password"

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

Building from Source

If you prefer to build from source:

# 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. Sign in with email and password (local auth), or use the SSO button if you configured OIDC
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

Choose either backend. Logchef does not copy data between them; a source points at logs that already exist in ClickHouse or VictoriaLogs.

ClickHouse from the Docker setup

1. Navigate to Sources > Manage Sources
2. Click “Add Source”
3. Enter your ClickHouse connection details:

   Name: Demo Logs
   Host: clickhouse:9000 (Docker) or localhost:9000 (host process)
   Database: default
   Table: logs
   Timestamp Field: timestamp
   Severity Field: severity_text

4. Test the connection and save

VictoriaLogs

For a local VictoriaLogs instance, first ingest the sample from the end-to-end VictoriaLogs example. Then choose VictoriaLogs in the Add Source form and use:

Name: VictoriaLogs Demo
Base URL: http://victorialogs:9428
Authentication: No Auth
Timestamp Field: _time
Severity Field: level

If Logchef runs in Docker and VictoriaLogs is another container, both containers must share a network and the base URL must use the VictoriaLogs service or container name, for example http://victorialogs:9428. From inside a container, localhost refers to that same container.

Choose Validate Connection, then save the source. Validation checks health, field discovery, and real query access.

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"

Search for specific text in the log body with ~, the case-insensitive substring operator:

namespace="syslog" and body~"error"

For the VictoriaLogs sample, the same LogchefQL workflow looks like:

env="demo" and level="error"

Switch the editor to LogsQL when you need the native language:

env:="demo" AND level:="error" | fields _time, service, level, _msg

Build Your First Dashboard

1. Open Dashboards and choose New dashboard
2. Open the dashboard, choose Edit, then Add panel
3. Pick a team and source, enter a LogchefQL filter, and choose a time series, stat, breakdown, or table panel
4. Use group by on a time series or breakdown to split counts by a field such as service or severity
5. Add panels from either ClickHouse or VictoriaLogs, arrange the grid, and save

Every panel follows one dashboard time range and refresh interval. See Dashboards for a VictoriaLogs example, native LogsQL behavior, permissions, and result caching.

Next Steps

• Learn more about the search syntax
• Explore advanced querying examples
• Set up Vector integration for your own logs
• Connect VictoriaLogs end to end
• Build a mixed-source dashboard
• Learn about user management