Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

9.2 KB
Raw Blame
---
title: Get started with self-hosting
description: This is a simple guide how to get started with OpenPanel on your own VPS.
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { SelfHostingVersionBanner } from '@/components/self-hosting-version-banner';

<SelfHostingVersionBanner />

## Instructions

### Prerequisites

- A VPS of any kind (only tested on Ubuntu 24.04)
  - We recommend using [Hetzner (affiliate link)](https://hetzner.cloud/?ref=7Hq0H5mQh7tM). Use the link if you want to support us. 🫢
  - πŸ™‹β€β™‚οΈ This works on any Linux server (x64 or arm64) that can run Docker. The CLI offers to install Docker for you.
- At least 4GB RAM (Redpanda, ClickHouse and Postgres run side by side)
- A domain name pointing at the server, if you want automatic HTTPS

### Quickstart

```bash
curl -fsSL https://raw.githubusercontent.com/Openpanel-dev/openpanel/main/self-hosting/install.sh | sh
openpanel init
```

<Steps>

<Step>
### Install the CLI

The `openpanel` CLI is a single file with no dependencies. The script downloads the right build for your machine, checks its checksum, and puts it on your `PATH`.

```bash
curl -fsSL https://raw.githubusercontent.com/Openpanel-dev/openpanel/main/self-hosting/install.sh | sh
```

You can also download a binary from the [releases page](https://github.com/Openpanel-dev/openpanel/releases): every OpenPanel release includes the CLI for Linux (x64 and arm64), with a `checksums.txt`.
</Step>
<Step>
### Run the setup

```bash
openpanel init
```

It checks that Docker is installed and running (on Linux it offers to install it), then asks a few questions:

1. Where OpenPanel will live (your URL)
2. Whether to run Postgres, ClickHouse and Redis for you, or use your own
3. Whether to use the bundled Caddy (automatic HTTPS) or your own reverse proxy
4. A [Resend](https://resend.com) key for email (optional)

Everything else is generated for you: secrets, the worker count, and the password for the queue dashboard. The files are written to `~/openpanel`. Pass `--dir <path>` to put them somewhere else.

Running unattended? Pass the answers as flags:

```bash
openpanel init --yes --domain https://analytics.example.com
```
</Step>
<Step>
### Start πŸš€

```bash
openpanel up
```
</Step>
</Steps>

## Good to know

### Always use correct api url

When self-hosting you'll need to provide your api url when initializing the SDK.

The path should be `/api` and the domain should be your domain.

```html title="index.html"
<script>
  window.op=window.op||function(){var n=[];return new Proxy(function(){arguments.length&&n.push([].slice.call(arguments))},{get:function(t,r){return"q"===r?n:function(){n.push([r].concat([].slice.call(arguments)))}} ,has:function(t,r){return"q"===r}}) }();
  window.op('init', {
    apiUrl: 'https://your-domain.com/api', // [!code highlight]
    clientId: 'YOUR_CLIENT_ID',
    trackScreenViews: true,
    trackOutgoingLinks: true,
    trackAttributes: true,
  });
</script>
<script src="https://openpanel.dev/op1.js" defer async></script>
```

```js title="op.ts"
import { OpenPanel } from '@openpanel/sdk';

const op = new OpenPanel({
  apiUrl: 'https://your-domain.com/api', // [!code highlight]
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});
``` 

### E-mail

Some of OpenPanel's features require e-mail. We use Resend as our transactional e-mail provider by default, but you can also use your own SMTP server. To enable email features, set the relevant environment variables described below.

<Callout>This is nothing that is required for the basic setup, but it is required for some features.</Callout>

Features that require e-mail:

- Password reset
- Invitations
- more will be added over time

#### Option A β€” Resend

Create an account on [resend.com](https://resend.com), verify your sender domain, and set the `RESEND_API_KEY` environment variable.

```bash title=".env"
RESEND_API_KEY=re_xxxxxxxxxxxxx
EMAIL_SENDER=[email protected]
```

#### Option B β€” SMTP

If you prefer to use your own SMTP server, set `SMTP_HOST` and OpenPanel will use it instead of Resend.

```bash title=".env"
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=[email protected]
SMTP_PASS=your-smtp-password
EMAIL_SENDER=[email protected]
```

<Callout type="info">
`SMTP_HOST` takes priority over `RESEND_API_KEY` if both are set. If neither is configured, emails are logged to the console instead of being sent.
</Callout>

For email configuration details, see the [Environment Variables documentation](/docs/self-hosting/environment-variables#email).

### AI integration

OpenPanel includes an AI-powered analytics assistant that can help you analyze data, create reports, and answer questions about your analytics. It supports both OpenAI and Anthropic β€” set one or both keys and the model picker in the chat will only show models whose provider has a key configured.

#### Supported Models

- **OpenAI** β€” `GPT-4.1`, `GPT-4.1 mini`, `GPT-5.4 mini`
- **Anthropic** β€” `Claude Haiku 4.5`, `Claude Sonnet 4.6`, `Claude Opus 4.6`

#### Configuration

Add one or both of the following to your `.env` file in your install directory, then run `openpanel reload`:

```bash title=".env"
# OpenAI β€” get a key at platform.openai.com/api-keys
OPENAI_API_KEY=sk-your-openai-api-key-here

# Anthropic β€” get a key at console.anthropic.com
ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here
```

<Callout type="info">
The AI assistant is optional. Without either key set, the chat drawer still opens but shows a setup hint β€” every other OpenPanel feature continues to work normally.
</Callout>

<Callout type="warn">
AI features will incur costs based on your usage and the model you choose. Monitor your API usage through your provider's dashboard to avoid unexpected charges.
</Callout>

For complete AI configuration details, see the [Environment Variables documentation](/docs/self-hosting/environment-variables#ai-features).

### Managed Redis

If you use a managed Redis service, you may need to set the `notify-keyspace-events` manually.

Without this setting we won't be able to listen for expired keys which we use for calculating currently active visitors.

> You will see a warning in the logs if this needs to be set manually.

### Registration / Invitations

By default registrations are disabled after the first user is created.

You can change this by setting the `ALLOW_REGISTRATION` environment variable to `true`.

```bash title=".env"
ALLOW_REGISTRATION=true
```

Invitations are enabled by default. You can also disable invitations by setting the `ALLOW_INVITATION` environment variable to `false`.

```bash title=".env"
ALLOW_INVITATION=false
```

For a complete reference of all environment variables, see the [Environment Variables documentation](/docs/self-hosting/environment-variables).

## Helpful commands

Run these anywhere: the CLI finds your install (the current directory, `./self-hosting` in an old git clone, the last install it used, or a running OpenPanel stack) and prints which one it picked. Pass `--dir <path>` to choose explicitly.

### Basic Operations

```bash
openpanel up        # Start all OpenPanel services
openpanel down      # Stop all OpenPanel services
openpanel reload    # Apply changes to .env or docker-compose.yml
openpanel restart   # Recreate every container (a full restart)
openpanel logs      # Follow logs (openpanel logs op-api for one service)
openpanel status    # Show running services
```

### Changed your .env?

```bash
openpanel reload
```

This applies your changes: it checks `.env` for mistakes first, then recreates only the services whose settings changed, so your databases keep running. `docker compose restart` does **not** pick up `.env` changes; the containers keep their old values.

### Diagnose

```bash
openpanel doctor          # Check Docker, memory, and your docker-compose.yml / .env
openpanel doctor --fix    # Repair what it can (originals are kept as <file>.bak)
openpanel doctor --check  # Exit non-zero on errors, for scripts
```

### Move your data

```bash
openpanel export --out ./op-export   # Dump ClickHouse data as JSONL
```

The dump is gzipped JSONL per table and day, plus a `manifest.jsonl` and `_meta.json`. Filter it with `--project-id`, `--from` and `--to`, or list candidate containers with `--list` if auto-detection can't find ClickHouse.

### Troubleshooting

```bash
openpanel reset   # ⚠️ Deletes this install's data volumes
                  # Only use this if you want to start fresh!
```

<Callout>
`openpanel reset` deletes your databases and queues. It only touches this install's own data volumes (your config and HTTPS certificates are kept), and asks you to type the directory name before it does anything. Export first if you need the events.
</Callout>

## Updating

```bash
openpanel upgrade
```

This updates the CLI itself (after verifying its checksum), runs `doctor` to bring your `docker-compose.yml` and `.env` up to date with the new version, pulls the new images and restarts the stack. It shows what it will change and asks first.

Also read any changes in the [changelog](/docs/self-hosting/changelog).

<Callout>
  Coming from the `./setup` / `./update` scripts? Install the CLI as shown above and run `openpanel doctor` in your existing directory. It works on installs made by the old scripts too.
</Callout>