docs: add sections for popular deployment methods
This commit is contained in:
Carl-Gerhard Lindesvärd
279
apps/public/content/docs/self-hosting/deploy-dokploy.mdx
Normal file
279
apps/public/content/docs/self-hosting/deploy-dokploy.mdx
Normal file
@@ -0,0 +1,279 @@
|
||||
---
|
||||
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
|
||||
NEXT_PUBLIC_API_URL=https://yourdomain.com/api
|
||||
NEXT_PUBLIC_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 `NEXT_PUBLIC_API_URL` and `NEXT_PUBLIC_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):
|
||||
|
||||
- `NEXT_PUBLIC_API_URL` - Full API URL (e.g., `https://analytics.example.com/api`)
|
||||
- `NEXT_PUBLIC_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 NEXT_PUBLIC_API_URL is set correctly
|
||||
docker exec <op-api-container> env | grep NEXT_PUBLIC_API_URL
|
||||
docker exec <op-dashboard-container> env | grep NEXT_PUBLIC_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 `NEXT_PUBLIC_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 `NEXT_PUBLIC_API_URL` and `NEXT_PUBLIC_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://dokploy.com/docs)
|
||||
- [OpenPanel GitHub Issue #292](https://github.com/Dokploy/templates/issues/292) - Discussion about Dokploy deployment
|
||||
|
||||
Reference in New Issue
Block a user