280 lines
8.2 KiB
Plaintext
280 lines
8.2 KiB
Plaintext
---
|
|
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';
|
|
|
|
[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=noreply@yourdomain.com
|
|
```
|
|
|
|
<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
|
|
|