224 lines
6.4 KiB
Plaintext
224 lines
6.4 KiB
Plaintext
---
|
|
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';
|
|
|
|
## 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. So to get this working you'll need to create an account on Resend and set the `RESEND_API_KEY` environment variable.
|
|
|
|
<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
|
|
|
|
### 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):**
|
|
|
|
```bash title=".env"
|
|
OPENAI_API_KEY=sk-your-openai-api-key-here
|
|
AI_MODEL=gpt-4o-mini # Optional: defaults to gpt-4o-mini
|
|
```
|
|
|
|
**For Anthropic:**
|
|
|
|
```bash title=".env"
|
|
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](https://platform.openai.com/api-keys)
|
|
- **Anthropic**: Get your API key from [console.anthropic.com](https://console.anthropic.com)
|
|
|
|
<Callout type="info">
|
|
The AI assistant is optional. Without an API key configured, the AI chat feature will not be available, but all other OpenPanel features will continue 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>
|
|
|
|
|
|
|
|
### 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`.
|
|
|
|
```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
|
|
```
|
|
|
|
## 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. |