Get started with self-hosting

Instructions

Prerequisites

• VPS of any kind (only tested on Ubuntu 24.04)
  • We recommend using Hetzner (affiliate link). 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

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

git clone -b self-hosting https://github.com/Openpanel-dev/openpanel.git

cd openpanel/self-hosting
./setup

./start

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.

<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', 
    clientId: 'YOUR_CLIENT_ID',
    trackScreenViews: true,
    trackOutgoingLinks: true,
    trackAttributes: true,
  });
</script>
<script src="https://openpanel.dev/op1.js" defer async></script>

import { OpenPanel } from '@openpanel/sdk';

const op = new OpenPanel({
  apiUrl: 'https://your-domain.com/api', 
  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. To enable email features, create an account on Resend and set the RESEND_API_KEY environment variable.

Features that require e-mail:

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

For email configuration details, see the Environment Variables documentation.

AI integration

OpenPanel includes an AI-powered analytics assistant that can help you analyze data, create reports, and answer questions about your analytics. To enable this feature, you need to configure an API key for either OpenAI or Anthropic.

Supported Models

• OpenAI (default)
  • gpt-4o - More powerful but higher cost
  • gpt-4o-mini - Default model, good balance of performance and cost
• Anthropic
  • claude-3-5-haiku-latest - Fast and cost-effective

Configuration

Add the following environment variables to your .env file in the self-hosting directory:

For OpenAI (default):

OPENAI_API_KEY=sk-your-openai-api-key-here
AI_MODEL=gpt-4o-mini  # Optional: defaults to gpt-4o-mini

For Anthropic:

ANTHROPIC_API_KEY=your-anthropic-api-key-here
AI_MODEL=claude-3-5

Getting API Keys

• OpenAI: Get your API key from platform.openai.com/api-keys
• Anthropic: Get your API key from console.anthropic.com

For complete AI configuration details, see the Environment Variables documentation.

Managed Redis

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

Without this setting we wont be able to listen for expired keys which we use for caluclating currently active vistors.

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.

ALLOW_REGISTRATION=true

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

ALLOW_INVITATION=false

For a complete reference of all environment variables, see the Environment Variables documentation.

Helpful scripts

OpenPanel comes with several utility scripts to help manage your self-hosted instance:

Basic Operations

./start    # Start all OpenPanel services
./stop     # Stop all OpenPanel services
./logs     # View real-time logs from all services

Maintenance

./rebuild <service-name>    # Rebuild and restart a specific service
                            # Example: ./rebuild op-dashboard

Troubleshooting

./danger_wipe_everything   # ⚠️ Removes all containers, volumes, and data
                           # Only use this if you want to start fresh!

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.

Also read any changes in the changelog and apply them to your instance.