selfhost.directory

The index of self-hostable projects — ranked, categorized and served with live updates.
Own your data and stop giving it to big tech.

telescope logo

Self-host telescope

v0.0.27

Web-based log viewer for ClickHouse, StarRocks, Docker, K8s

BetaOpen SourceMIT
Updated5 months ago
LanguagePython
Setup difficultyModerate
ThemeDark mode
Stars
712
Port
9898 (HTTP web interface)
Docker
ghcr.io/iamtelescope/telescope
Install with Docker
Telescope data explorer in light themeTelescope data explorer in dark themeSources management in light themeSources management in dark themeSearch and filter interface in light themeSearch and filter interface in dark themeData visualization in light themeData visualization in dark themeAccess control interface in light themeAccess control interface in dark theme

What is telescope?

Telescope is a web-based log viewer UI that provides a unified interface for exploring log data stored in ClickHouse, StarRocks, Docker, and Kubernetes. It supports multiple data source connections with configurable field mappings, autocompletion, and role-based access control per source. Users can filter and search logs using structured filters or raw SQL WHERE clauses, visualize data with interactive charts grouped by any field including nested JSON, and save filter presets as shared views. Authentication supports local username/password, GitHub OAuth with organization restrictions, and Okta OAuth with PKCE. The application runs as a Docker container (ghcr.io/iamtelescope/telescope) on port 9898 with a SQLite database for its own metadata, while log data lives in the external sources. It is currently in beta (version 0.0.27) with breaking changes between releases requiring database migrations.

Should you self-host telescope?

telescope scores 49/100 on selfhost.directory (how scoring works) and ranks #6 of 13 in Log Management. It has 712 GitHub stars.

It shipped 5 stable releases in the past year. The latest, v0.0.27, came out on 8 May 2026. New versions land roughly every 2 weeks.

Setup is moderate: expect some configuration beyond a single command. An official Docker image is available. It is MIT-licensed and written mostly in Python.

Its closest alternative on selfhost.directory is Dozzle (77/100, 14 752 stars). It scores higher overall, so compare the two before you pick. See telescope vs Dozzle side by side.

Features

  • Data Visualization
  • FlyQL query language
  • Focus mode
  • GitHub OAuth authentication
  • Multi-source log exploration
  • Okta OAuth authentication
  • Raw SQL querying
  • Role-based Access Control
  • Saved Views
  • Structured log filtering

telescope README

How to install telescope

Install telescope with Docker

Docker
Environment variables
TELESCOPE_CONFIG_FILE

docker pull ghcr.io/iamtelescope/telescope:0.0.27 mkdir ~/.telescope/ wget -O ~/.telescope/db.sqlite3 "https://raw.githubusercontent.com/iamtelescope/telescope/refs/heads/main/dev/db.sqlite3" wget -O ~/.telescope/config.yaml "https://raw.githubusercontent.com/iamtelescope/telescope/refs/heads/main/dev/config.yaml" docker run
-e TELESCOPE_CONFIG_FILE="/config.yaml"
-v $(realpath ~/.telescope/config.yaml):/config.yaml
-v $(realpath ~/.telescope/db.sqlite3):/db.sqlite3
--network host
ghcr.io/iamtelescope/telescope:0.0.27

Requires Docker installed. Uses SQLite for internal metadata, external sources for log data.

How to configure telescope

  • auth.enable_testing_authfalseAlways authenticate without any conditions. For development use only.

    Always authenticate without any conditions. For development use only.

  • auth.force_auth_providerForce login via a specific provider: github or okta

    Force login via a specific provider: github or okta

    values: github, okta

  • auth.local_login_secret_pathSecret URL segment for emergency local login when forced auth is enabled

    Secret URL segment for emergency local login when forced auth is enabled

  • auth.providers.github.client_idGitHub OAuth app client ID

    GitHub OAuth app client ID

  • auth.providers.github.default_groupGroup to add users to on first login

    Group to add users to on first login

  • auth.providers.github.enabledfalseEnable login via GitHub

    Enable login via GitHub

  • auth.providers.github.keyGitHub OAuth app key

    GitHub OAuth app key

  • auth.providers.github.secretGitHub OAuth app secret

    GitHub OAuth app secret

  • auth.providers.okta.base_urlOkta base URL (e.g. https://yourcompany.okta.com)

    Okta base URL (e.g. https://yourcompany.okta.com)

  • auth.providers.okta.client_idOkta OAuth client ID

    Okta OAuth client ID

  • auth.providers.okta.default_groupGroup to add users to on first login

    Group to add users to on first login

  • auth.providers.okta.enabledfalseEnable login via Okta

    Enable login via Okta

  • auth.providers.okta.pkce_enabledtrueEnable PKCE for enhanced security

    Enable PKCE for enhanced security

  • auth.providers.okta.scopeopenid profile emailOAuth scopes to request (space-separated)

    OAuth scopes to request (space-separated)

  • auth.providers.okta.secretOkta OAuth client secret

    Okta OAuth client secret

  • auth.testing_auth_usernametelescopeUsername to use when enable_testing_auth is enabled

    Username to use when enable_testing_auth is enabled

  • django.ALLOWED_HOSTSList of allowed hostnames

    List of allowed hostnames

  • django.CACHESdatabase cacheDjango cache configuration

    Django cache configuration

  • django.CSRF_TRUSTED_ORIGINSList of trusted origins for CSRF validation

    List of trusted origins for CSRF validation

  • django.DATABASESSQLiteDjango database configuration

    Django database configuration

  • django.DEBUGfalseEnable Django debug mode

    Enable Django debug mode

  • frontend.base_urlURL subpath for running behind a reverse proxy

    URL subpath for running behind a reverse proxy

  • frontend.docs_urlDocs URL shown in the top bar

    Docs URL shown in the top bar

  • frontend.github_urlGitHub URL shown in the top bar

    GitHub URL shown in the top bar

  • frontend.show_docs_urltrueShow the docs link in the top navigation bar

    Show the docs link in the top navigation bar

  • frontend.show_github_urltrueShow the GitHub link in the top navigation bar

    Show the GitHub link in the top navigation bar

  • gunicorn.bind127.0.0.1:9898Address and port to listen on

    Address and port to listen on

  • gunicorn.max_requests50Max requests a worker handles before being restarted

    Max requests a worker handles before being restarted

  • gunicorn.max_requests_jitter50Random jitter added to max_requests

    Random jitter added to max_requests

  • gunicorn.timeout120Worker timeout in seconds

    Worker timeout in seconds

  • gunicorn.workers8Number of worker processes

    Number of worker processes

  • limits.max_saved_views_per_user0Maximum number of saved views a user can create

    Maximum number of saved views a user can create

  • logging.formatdefaultLog output format

    Log output format

    values: default, dev, json

  • logging.levelsLog level overrides per logger

    Log level overrides per logger

  • TELESCOPE_CONFIG_FILEPath to the YAML configuration file

    Path to the YAML configuration file

telescope releases & version history

More in Log Management

Rate this project

Click to rate — no account needed.

0 comments

Posting as guest
Loading comments…