OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
---
title: Get started with self-hosting (2.x)
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 version="v2" />
## Instructions
### Prerequisites
- 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 should work on any system if you have pre-installed docker, node and pnpm
### Quickstart
```bash
git clone -b self-hosting https://github.com/Openpanel-dev/openpanel && cd openpanel/self-hosting && ./setup
# After setup is complete run `./start` to start OpenPanel
```
<Steps>
<Step>
### Clone
Clone the repository to your VPS and checkout the self-hosting tag
```bash
git clone -b self-hosting https://github.com/Openpanel-dev/openpanel.git
```
</Step>
<Step>
### Run the setup script
The setup script will do 3 things
1. Install node (if you accept)
2. Install docker (if you accept)
3. Execute a node script that will ask some questions about your setup
> Setup takes 30s to 2 minutes depending on your VPS
```bash
cd openpanel/self-hosting
./setup
```
β οΈ If the `./setup` script fails to run, you can do it manually.
1. Install docker
2. Install node
3. Install npm
4. Run the `npm run quiz` script inside the self-hosting folder
</Step>
<Step>
### Start π
Run the `./start` script located inside the self-hosting folder
```bash
./start
```
</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 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
[email protected]
SMTP_PASS=your-smtp-password
[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 the `self-hosting` directory, then restart the API service:
```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 scripts
OpenPanel comes with several utility scripts to help manage your self-hosted instance:
### Basic Operations
```bash
./start # Start all OpenPanel services
./stop # Stop all OpenPanel services
./logs # View real-time logs from all services
```
### Maintenance
```bash
./rebuild <service-name> # Rebuild and restart a specific service
# Example: ./rebuild op-dashboard
```
### Troubleshooting
```bash
./danger_wipe_everything # β οΈ Removes all containers, volumes, and data
# Only use this if you want to start fresh!
```
<Callout>
The `danger_wipe_everything` script will delete all your OpenPanel data including databases, configurations, and cached files. Use with extreme caution!
</Callout>
All these scripts should be run from within the `self-hosting` directory. Make sure the scripts are executable (`chmod +x script-name` if needed).
## Updating
To grab the latest and greatest from OpenPanel you should just run the `./update` script inside the self-hosting folder.
<Callout>
If you don't have the `./update` script, you can run `git pull` and then `./update`
</Callout>
Also read any changes in the [changelog](/docs/self-hosting/changelog) and apply them to your instance.