Skip to main content

Self Hosting

Logflare can be self-hosted. As of now, only a single machine setup is supported.

Two different backends are supported:

  • BigQuery
  • PostgreSQL (experimental)

Docker-compose is the recommended way to manage single node deployments.


Inviting team users and other team-related functionality is currently not supported, as Logflare self-hosted is currently intended for single-user experience only.

All browser authentication will be disabled when in single-tenant mode.


Common Configuration

Env VarTypeDescription
LOGFLARE_SINGLE_TENANTBoolean, defaults to falseIf enabled, a singular user will be seeded. All browser usage will default to the user.
LOGFLARE_API_KEYstring, defaults to nilIf set, this API Key can be used for interacting with the Logflare API. API key will be automatically generated if not set.
LOGFLARE_SUPABASE_MODEBoolean, defaults to falseA special mode for Logflare, where Supabase-specific resources will be seeded. Intended for Suapbase self-hosted usage.
PHX_HTTP_PORTInteger, defaults to 4000Allows configuration of the HTTP server port.
DB_SCHEMAString, defaults to nilAllows configuration of the database schema to scope Logflare operations.
LOGFLARE_LOG_LEVELString, defaults to info.
Options: error,warning, info
Allows runtime configuration of log level.
LOGFLARE_NODE_HOSTstring, defaults to node host on startup, which affects the node name logflare@<host>
LOGFLARE_LOGGER_METADATA_CLUSTERstring, defaults to nilSets global logging metadata for the cluster name. Useful for filtering logs by cluster name.
LOGFLARE_PUBSUB_POOL_SIZEInteger, defaults to 10Sets the number of Phoenix.PubSub.PG2 partitions to be created. Should be configured to the number of cores of your server for optimal multi-node performance.
LOGFLARE_ALERTS_ENABLEDBoolean, defaults to trueFlag for enabling and disabling query alerts.
LOGFLARE_ALERTS_MIN_CLUSTER_SIZEInteger, defaults to 1Sets the required cluster size for Query Alerts to be run. If cluster size is below the provided value, query alerts will not run.
LOGFLARE_MIN_CLUSTER_SIZEInteger, defaults to 1Sets the target cluster size, and emits a warning log periodically if the cluster is below the set number of nodes..
LOGFLARE_OTEL_ENDPOINTString, defaults to nilSets the OpenTelemetry Endpoint to send traces to via gRPC. Port number can be included, such as
LOGFLARE_OTEL_SOURCE_UUIDString, defaults to nil, optionally required for OpenTelemetry.Sets the appropriate header for ingesting OpenTelemetry events into a Logflare source.
LOGFLARE_OTEL_ACCESS_TOKENString, defaults to nil, optionally required for OpenTelemetry.Sets the appropriate authentication header for ingesting OpenTelemetry events into a Logflare source.
LOGFLARE_OPEN_TELEMETRY_SAMPLE_RATIOFloat, defaults to 0.001, optionally required for OpenTelemetry.Sets the sample ratio for server traces. Ingestion and Endpoint routes are dropped and are not included in tracing.

LOGFLARE_OPEN_TELEMETRY_SAMPLE_RATIO Additional environment variable configurations for the OpenTelemetry libraries used can be found here.perf/bq-pipeline-sharding

BigQuery Backend Configuration

Env VarTypeDescription
GOOGLE_PROJECT_IDstring, requiredSpecifies the GCP project to use.
GOOGLE_PROJECT_NUMBERstring, requiredSpecifies the GCP project to use.
GOOGLE_DATASET_ID_APPENDstring, defaults to _prodThis allows customization of the dataset created in BigQuery.

PostgreSQL Backend Configuration

Env VarTypeDescription
POSTGRES_BACKEND_URLstring, requiredPostgreSQL connection string, for connecting to the database. User must have sufficient permssions to manage the schema.
POSTGRES_BACKEND_SCHEMAstring, optional, defaults to publicSpecifies the database schema to scope all operations.

BigQuery Setup


You will need a Google Cloud project with billing enabled in order to proceed.

The requirements for server startup are as follows after creating the project:

  • Project ID
  • Project number
  • A service account key

Setting up BigQuery Service Account

To ensure that you have sufficient permissions to insert into your Google Cloud BigQuery, ensure that you have created a service account with either:

  • BigQuery Admin role; or
  • The following permissions:
    • bigquery.datasets.create
    • bigquery.datasets.get
    • bigquery.datasets.getIamPolicy
    • bigquery.datasets.update
    • bigquery.routines.create
    • bigquery.routines.update
    • bigquery.tables.create
    • bigquery.tables.delete
    • bigquery.tables.get
    • bigquery.tables.getData
    • bigquery.tables.update
    • bigquery.tables.updateData

We recommend setting the BigQuery Admin role, as it simplifies permissions setup.

Obtaining the BigQuery Service Account Key

In order for Logflare to connect sources to their relevant BigQuery tables, we would need to have a service account key that can sign the JWTs needed to authenticate with the Google Cloud APIs.

To obtain the BigQuery service account key after creating it, navigate to IAM > Service Accounts in the web console and click on the "Manage Keys" action option.

Service Account List Manage Keys Action

Thereafter, click on "Add Key" to create a new key. The key will be in a JSON format. Store this key securely on your host machine.

Add Key Button

You can also obtain the key via the gcloud cli by following the official documentation.

Deployment with Docker Compose

Using docker compose is the recommended method for self-hosting.

  1. Create the docker-compose.yml
image: postgres:13.4-alpine
POSTGRES_DATABASE: logflare_docker
- "5432:5432"
- ./priv/wal.sql:/docker-entrypoint-initdb.d/wal.sql
- pg-data:/var/lib/postgresql/data
image: supabase/logflare:1.0.1
- "4000:4000"
- DB_DATABASE=logflare_docker
- DB_PORT=5432
- DB_PASSWORD=postgres
- DB_USERNAME=postgres
- LOGFLARE_API_KEY=my-cool-api-key

# Required for BigQuery backend
- GOOGLE_PROJECT_ID=logflare-docker-example

# Required for Postgres backend
- POSTGRES_BACKEND_URL=postgresql://user:pass@host:port/db
- type: bind
source: ${PWD}/.env
target: /tmp/.secrets.env
read_only: true
- type: bind
source: ${PWD}/gcloud.json
target: /opt/app/rel/logflare/bin/gcloud.json
read_only: true
- db
  1. Using the Service Account key that you had obtained under the pre-requisites section, move and rename the JSON file to gcloud.json in your working directory.

The directory structure should be as follows:

|- gcloud.json
|- docker-compose.yml
  1. Run docker-compose up -d and visit http://localhost:4000

Using an .env file

You can optionally use a .env file to manage your environemnts. You can base the file contents on this reference file


You cannot have comments in the env file as we load it at startup via xargs.

# ... the rest is the same
# add in this bind bound. If you have a different name or location, update the source
- type: bind
source: ${PWD}/.env
target: /tmp/.secrets.env
read_only: true

The directory structure will now be as follows:

|- gcloud.json
|- .env
|- docker-compose.yml

Protecting the User Interface

When self-hosting, it is advised to protect the user interface with minimally basic HTTP authentication. How this is achieved is left to the self-hoster.

When applying such authentication rules, we recommend requiring all routes to be authenticated except for the following paths, as illustrated using glob patterns:


the /logs path is for legacy reasons and is mostly for compatibility with older Logflare libraries.