--- 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'; ## 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 ``` ### 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`. ### 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 ` to put them somewhere else. Running unattended? Pass the answers as flags: ```bash openpanel init --yes --domain https://analytics.example.com ``` ### Start 🚀 ```bash openpanel up ``` ## 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" ``` ```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. This is nothing that is required for the basic setup, but it is required for some features. 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=noreply@yourdomain.com ``` #### 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=smtp-user@example.com SMTP_PASS=your-smtp-password EMAIL_SENDER=noreply@yourdomain.com ``` `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. 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 ``` 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. 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. 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). ### Running without outbound calls A self-hosted dashboard loads its scripts, fonts, maps and logos from your own server. With `SELF_HOSTED` set, which `openpanel init` does for you, it also skips the UserJot feedback widget that OpenPanel Cloud loads, and "Give feedback" becomes a plain link to our public board. Two things still leave your server by default. Turn them off in `.env`: ```bash title=".env" DISABLE_PING=true DISABLE_FAVICON_FETCH=true ``` | Variable | What it stops | | --- | --- | | `DISABLE_PING` | The daily usage ping to `api.openpanel.dev`, which sends your dashboard URL and total event count | | `DISABLE_FAVICON_FETCH` | Favicon lookups from the API to `icons.duckduckgo.com` and `www.google.com` (which can redirect to `*.gstatic.com`). Referrers and pages show no favicon, but the bundled browser, OS and device logos stay | Run `openpanel reload` after changing `.env`. If your setup lists environment variables per service, as the Coolify template does, set `DISABLE_FAVICON_FETCH` on the API and `DISABLE_PING` on the worker. The rest only happens when you use the feature that needs it: - **Email**: Resend or your SMTP server. Emails also show a logo hosted on `cdn.jsdelivr.net`, which the recipient's mail client loads. - **AI chat**: your OpenAI or Anthropic endpoint. Its docs tool reads `openpanel.dev/llms-full.txt` and carries on without it if that fails. - **Integrations and sign-in**: Slack, Discord, webhooks, S3 and GCS exports, Google Search Console, social login and imports from Mixpanel or Amplitude talk to those services. - **Profile avatars**: if your events set an avatar URL, the browser viewing the profile loads it from that URL. - **The `openpanel` CLI**: checks GitHub for new releases, and `init` and `upgrade` pull images from a registry. - **Public tool routes**: `/tools/site-checker` and `/tools/ip-lookup` on the API make their own lookups when called. The dashboard doesn't use them. Links in the dashboard, such as Docs, go to `openpanel.dev` only when someone clicks them. We have not tested a full install on a network with no outbound access, so check your own setup before relying on this. Install, upgrades and image pulls need a registry you can reach. ## 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 ` 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 .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! ``` `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. ## 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). 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.