Self-Hosting Guide
Run FeedbackFlow on your own infrastructure
Self-Hosting Philosophy
FeedbackFlow is designed to be truly self-hostable, like n8n. There are no artificial limits, no phone-home telemetry, and no license checks. You get the full application with all features.
Full Control
Your data stays on your servers. No external dependencies required.
No License Keys
No activation, no license servers. Just deploy and run.
Fully Configurable
Swap out providers for auth, storage, and more.
Quick Start
Get FeedbackFlow running locally in under 5 minutes.
1. Clone the repository
git clone https://github.com/feedbackflow/feedbackflow.git cd feedbackflow2. Install dependencies
npm install3. Set up environment variables
cp .env.example .env.local # Edit .env.local with your configuration4. Start Convex (separate terminal)
npx convex dev5. Start the development server
npm run devDone! Open http://localhost:3000 in your browser.
Docker Compose Setup
For production deployments, we recommend using Docker Compose.
version: '3.8'
services:
feedbackflow:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- CONVEX_DEPLOYMENT=${CONVEX_DEPLOYMENT}
- NEXT_PUBLIC_CONVEX_URL=${NEXT_PUBLIC_CONVEX_URL}
- NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=${NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY}
- CLERK_SECRET_KEY=${CLERK_SECRET_KEY}
- STRIPE_SECRET_KEY=${STRIPE_SECRET_KEY}
- STRIPE_PUBLISHABLE_KEY=${STRIPE_PUBLISHABLE_KEY}
- STRIPE_WEBHOOK_SECRET=${STRIPE_WEBHOOK_SECRET}
- RESEND_API_KEY=${RESEND_API_KEY}
- ENCRYPTION_KEY=${ENCRYPTION_KEY}
restart: unless-stoppedStart with Docker Compose
docker-compose up -dFROM node:20-alpine AS base
# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
# Build the application
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED 1
RUN npm run build
# Production image
FROM base AS runner
WORKDIR /app
ENV NODE_ENV production
ENV NEXT_TELEMETRY_DISABLED 1
RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
USER nextjs
EXPOSE 3000
ENV PORT 3000
CMD ["node", "server.js"]Environment Variables
All configuration is done through environment variables. Create a .env.local file or set them in your hosting platform.
| Variable | Required | Description |
|---|---|---|
| Database (Convex) | ||
CONVEX_DEPLOYMENT | Yes | Your Convex deployment name |
NEXT_PUBLIC_CONVEX_URL | Yes | Your Convex deployment URL |
| Authentication (Clerk) | ||
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | Yes | Clerk publishable key (pk_...) |
CLERK_SECRET_KEY | Yes | Clerk secret key (sk_...) |
| Payments (Stripe) - Optional for self-host | ||
STRIPE_SECRET_KEY | No | Stripe secret key (sk_test_... or sk_live_...) |
STRIPE_PUBLISHABLE_KEY | No | Stripe publishable key |
STRIPE_WEBHOOK_SECRET | No | Stripe webhook signing secret (whsec_...) |
| Email (Resend) - Optional | ||
RESEND_API_KEY | No | Resend API key for transactional emails |
| Security | ||
ENCRYPTION_KEY | Yes | 32-byte key for encrypting API keys (generate with openssl rand -hex 32) |
Convex Database Options
Convex Cloud (Recommended)
The easiest option. Convex offers a generous free tier and handles all infrastructure for you.
- Sign up at convex.dev
- Run
npx convex devto create a deployment - Copy the deployment URL to your environment
Free tier includes: 1M function calls/month, 1GB storage, real-time sync
Self-Hosted Convex (Advanced)
Convex is working on a self-hosted option. Check their documentation for the latest status.
Note: Self-hosted Convex is not yet generally available. For full self-hosting, you may need to wait for this feature or consider adapting to a different backend.
Authentication Options
Clerk (Default)
FeedbackFlow uses Clerk for authentication out of the box. Clerk offers a generous free tier (10,000 MAU).
- Sign up at clerk.com
- Create an application
- Copy the API keys to your environment
Alternative Auth Providers
To use a different auth provider, you'll need to modify the codebase:
- NextAuth.js - Open source, supports many providers. Replace Clerk components with NextAuth.
- Supabase Auth - Part of Supabase, can be self-hosted. Good option if already using Supabase.
- Keycloak - Enterprise-grade, fully self-hosted identity management.
- Convex Auth - Native Convex authentication. Simpler setup, fewer moving parts.
Storage Configuration
External Storage for Videos
FeedbackFlow stores screenshots in Convex storage. For video recordings, you can configure external storage for better scalability.
Supported Providers
- Amazon S3 - Standard S3 with region selection
- Cloudflare R2 - S3-compatible with zero egress fees
- Google Cloud Storage - Service account authentication
- MinIO - Self-hosted S3-compatible storage
Configuration
Configure external storage in Settings → Storage. Enter your credentials and test the connection before enabling.
If no external storage is configured, FeedbackFlow falls back to Convex storage (50MB file size limit).
Self-Hosted MinIO Example
For fully self-hosted storage, set up MinIO:
# Add to docker-compose.yml
minio:
image: minio/minio:latest
ports:
- "9000:9000"
- "9001:9001"
environment:
- MINIO_ROOT_USER=minioadmin
- MINIO_ROOT_PASSWORD=minioadmin
command: server /data --console-address ":9001"
volumes:
- minio_data:/data
volumes:
minio_data:Then configure with endpoint http://minio:9000 in the storage settings.
No Telemetry, No Phone Home
FeedbackFlow does not:
- Send usage data to our servers
- Require license keys or activation
- Check for updates or validity
- Limit features based on deployment type
Your self-hosted instance is completely independent. The only external calls are to services you explicitly configure (Clerk, Stripe, AI providers, external storage).