Skip to content

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

8.3 KB
Raw Blame
---
title: Deploy with Dokploy
description: Deploy OpenPanel using Dokploy's Docker Compose template
---

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

<SelfHostingVersionBanner />

[Dokploy](https://dokploy.com) is an open-source, self-hosted platform for deploying applications. OpenPanel can be deployed on Dokploy using the Docker Compose template, with some specific configuration requirements.

<Callout type="warn">
⚠️ **Important**: The Dokploy template requires specific configuration that differs from Coolify. Make sure to follow all steps carefully, especially the environment variables and domain configuration.
</Callout>
<Callout type="warn">
⚠️ **Important**: We have an open issue on dokploy https://github.com/Dokploy/templates/issues/292 and hoping it will be resolved.
</Callout>

## Prerequisites

- A Dokploy instance installed and running
- A server with at least 2GB RAM (4GB+ recommended)
- Domain name configured in Dokploy

## Quick Start

<Steps>
<Step>
### Deploy OpenPanel Template

1. Log in to your Dokploy dashboard
2. Navigate to your project
3. Click **"New Application"** or **"Deploy"**
4. Select **"Docker Compose"** or search for **"OpenPanel"** template
5. Select the OpenPanel template
</Step>

<Step>
### Configure Domain Names

Configure your domain names in Dokploy:

1. Set up the main domain for the dashboard (e.g., `analytics.yourdomain.com`)
2. Configure the API domain - this should be the **same domain** as the dashboard, with the API path forwarded to `/api`

<Callout>
The API and dashboard use the same domain. The API service has a forward path to `/api`, so make sure to configure this correctly.
</Callout>
</Step>

<Step>
### Configure Environment Variables

Edit the `.env` file or environment variables in Dokploy. You **must** set these environment variables:

```bash
# Required: Set these to your actual domain
API_URL=https://yourdomain.com/api
DASHBOARD_URL=https://yourdomain.com

# Database Configuration (automatically set by Dokploy)
OPENPANEL_POSTGRES_DB=openpanel-db
SERVICE_USER_POSTGRES=postgres
SERVICE_PASSWORD_POSTGRES=<auto-generated>
SERVICE_PASSWORD_REDIS=<auto-generated>

# Optional Configuration
OPENPANEL_ALLOW_REGISTRATION=false
OPENPANEL_ALLOW_INVITATION=true
RESEND_API_KEY=your-resend-api-key
OPENPANEL_EMAIL_SENDER=[email protected]
```

<Callout type="warn">
⚠️ **Critical**: Unlike Coolify, Dokploy does not support `SERVICE_FQDN_*` variables. You **must** hardcode `API_URL` and `DASHBOARD_URL` with your actual domain values.
</Callout>
</Step>

<Step>
### Configure API Service Domain Settings

In Dokploy, configure the API service domain:

1. Go to the `op-api` service configuration
2. Set up the domain configuration:
   ```toml
   [[config.domains]]
   serviceName = "op-api"
   port = 3000
   host = "${api_domain}"
   ```
3. **Important**: Check the **"Strip external path"** checkbox for the API service

<Callout>
The "Strip external path" option is crucial! Without it, the API will receive incorrect paths when requests are forwarded from `/api`.
</Callout>
</Step>

<Step>
### Deploy

1. Review all configuration
2. Click **"Deploy"** or **"Save"**
3. Wait for all services to start and become healthy

Monitor the deployment logs to ensure all services start correctly.
</Step>

<Step>
### Verify Installation

Once deployment is complete:

1. Check that all services are running:
   - `op-api` - API server
   - `op-dashboard` - Dashboard (frontend)
   - `op-worker` - Background worker
   - `op-db` - PostgreSQL database
   - `op-kv` - Redis cache
   - `op-ch` - ClickHouse database

2. Access your dashboard at your configured domain
3. Try creating an account to verify the API is working correctly

<Callout type="warn">
If you're using Cloudflare in front of Dokploy, remember to purge the Cloudflare cache after making changes to ensure updated resources are served.
</Callout>
</Step>
</Steps>

## Configuration Details

### Required Environment Variables

For Dokploy, you **must** hardcode these variables (unlike Coolify, Dokploy doesn't support `SERVICE_FQDN_*` variables):

- `API_URL` - Full API URL (e.g., `https://analytics.example.com/api`)
- `DASHBOARD_URL` - Full Dashboard URL (e.g., `https://analytics.example.com`)

Dokploy automatically sets:
- `OPENPANEL_POSTGRES_DB` - PostgreSQL database name
- `SERVICE_USER_POSTGRES` - PostgreSQL username
- `SERVICE_PASSWORD_POSTGRES` - PostgreSQL password (auto-generated)
- `SERVICE_PASSWORD_REDIS` - Redis password (auto-generated)

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

### Domain Configuration

The API and dashboard services share the same domain:

- **Dashboard**: Serves the frontend at the root path (`/`)
- **API**: Serves the API at `/api` path

**Important settings for the API service:**
- Domain: Same as dashboard domain
- Path: `/api`
- **Strip external path**: ✅ **Must be checked**

This ensures that when requests come to `/api/*`, the path is correctly forwarded to the API service without the `/api` prefix.

## Troubleshooting

### API Requests Not Working

If API requests fail after deployment:

1. **Verify environment variables**:
   ```bash
   # Check that API_URL is set correctly
   docker exec <op-api-container> env | grep API_URL
   docker exec <op-dashboard-container> env | grep API_URL
   ```

2. **Check "Strip external path" setting**:
   - Go to API service configuration in Dokploy
   - Ensure "Strip external path" is **checked**

3. **Verify domain configuration**:
   - API service should have path `/api`
   - Dashboard service should be at root `/`

### Account Creation Not Working

If account creation fails:

1. Check API logs:
   ```bash
   # In Dokploy, view logs for op-api service
   ```

2. Verify `API_URL` matches your domain:
   - Should be `https://yourdomain.com/api`
   - Not `http://localhost:3000` or similar

3. Check that the API service is accessible:
   ```bash
   curl https://yourdomain.com/api/healthcheck
   ```

### Cloudflare Cache Issues

If you're using Cloudflare in front of Dokploy:

1. After deploying or updating, purge Cloudflare cache
2. This ensures updated resources are served immediately
3. You can do this from Cloudflare dashboard or API

### Database Connection Issues

If services can't connect to databases:

1. Verify database services are running:
   - `op-db` (PostgreSQL)
   - `op-kv` (Redis)
   - `op-ch` (ClickHouse)

2. Check environment variables are set:
   ```bash
   docker exec <op-api-container> env | grep DATABASE_URL
   ```

3. Verify service names match in docker-compose:
   - Database service names: `op-db`, `op-kv`, `op-ch`
   - These should match the hostnames in connection strings

## Docker Compose Structure

The OpenPanel template includes these services:

- **op-api**: OpenPanel API server
- **op-dashboard**: OpenPanel dashboard (frontend)
- **op-worker**: Background worker for processing events
- **op-db**: PostgreSQL database
- **op-kv**: Redis cache
- **op-ch**: ClickHouse analytics database

## Differences from Coolify

The Dokploy template differs from Coolify in these ways:

1. **Environment Variables**: 
   - Dokploy does not support `SERVICE_FQDN_*` variables
   - Must hardcode `API_URL` and `DASHBOARD_URL`

2. **Domain Configuration**:
   - Must manually configure domain paths
   - Must enable "Strip external path" for API service

3. **Service Discovery**:
   - Uses standard Docker Compose service names
   - No automatic FQDN resolution

## Updating OpenPanel

To update OpenPanel in Dokploy:

1. Pull the latest images:
   ```bash
   docker compose pull
   ```

2. Restart services:
   ```bash
   docker compose up -d
   ```

Or use Dokploy's UI to restart services.

## Next Steps

- [Configure email settings](/docs/self-hosting/self-hosting#e-mail) for password resets and invitations
- [Set up AI integration](/docs/self-hosting/self-hosting#ai-integration) for the analytics assistant
- [Configure SDK](/docs/self-hosting/self-hosting#always-use-correct-api-url) to track events from your applications

## Additional Resources

- [Dokploy Documentation](https://docs.dokploy.com/docs/core)
- [OpenPanel GitHub Issue #292](https://github.com/Dokploy/templates/issues/292) - Discussion about Dokploy deployment