Installation Guide

Complete step-by-step installation instructions for setting up FlowCampaign locally for development or deploying to production.

System Requirements

Minimum Requirements

Node.js: 18.x or higher
npm: 8.x or higher (or yarn/pnpm)
Git: Latest version
SQLite: 3.x (for local development)
Cloudflare Account (for production deployment)

Recommended Requirements

RAM: 8GB or more
Storage: 2GB free space
CPU: 2+ cores
OS: Linux, macOS, or Windows (WSL2 recommended for Windows)

Installation Methods

Method 1: Local Development Setup

Step 1: Clone Repository

git clone https://github.com/ns-software-solutions/flowcampaign.git
cd flowcampaign

Step 2: Install Dependencies

npm install
# or
yarn install
# or
pnpm install

Step 3: Configure Environment

# Copy example environment file
cp .env.example .env

Edit .env file with your configuration:

# App Configuration
NODE_ENV=development
APP_PORT=3000
APP_URL=http://localhost:3000

# Database Configuration
DATABASE_URL=file:./dev.db

# Authentication
JWT_SECRET=your-super-secret-jwt-key-change-this
SESSION_SECRET=your-session-secret-change-this

# Email Providers
ZEPTOMAIL_API_KEY=your-zeptomail-api-key
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

# File Storage
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760 # 10MB

# Rate Limiting
RATE_LIMIT_WINDOW=15
RATE_LIMIT_MAX=100

Step 4: Initialize Database

# Run database migrations
npm run db:migrate

# Seed initial data (optional)
npm run db:seed

Step 5: Start Development Server

# Frontend (React)
npm run dev:frontend
# Backend (Hono/Cloudflare Workers)
npm run dev:backend

Or start both with:

npm run dev

Step 6: Verify Installation

Open browser to http://localhost:3000
You should see the FlowCampaign login page
Default admin credentials:
- Email: admin@flowcampaign.com
- Password: admin123

Method 2: Docker Setup

Step 1: Install Docker

Ensure Docker and Docker Compose are installed on your system.

Step 2: Clone Repository

git clone https://github.com/ns-software-solutions/flowcampaign.git
cd flowcampaign

Step 3: Configure Docker Environment

# Copy Docker environment file
cp .env.docker.example .env.docker

Edit .env.docker with your settings.

Step 4: Start Docker Containers

docker-compose up -d

Step 5: Access Application

Frontend: http://localhost:3000
Backend API: http://localhost:8787
Database Admin: http://localhost:8080 (if enabled)

Method 3: Production Deployment (Cloudflare Workers)

Prerequisites

Cloudflare Account
Cloudflare Workers enabled
Wrangler CLI installed

Step 1: Install Wrangler CLI

npm install -g wrangler
# or
pnpm add -g wrangler

Step 2: Configure Wrangler

wrangler login

Step 3: Update Production Configuration

Create wrangler.toml or update existing:

name = "flowcampaign"
main = "src/backend/index.ts"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]

[vars]
NODE_ENV = "production"
DATABASE_URL = "your-turso-database-url"
JWT_SECRET = "your-production-jwt-secret"

[build]
command = "npm run build"

[[d1_databases]]
binding = "DB"
database_name = "flowcampaign-db"
database_id = "your-database-id"

Step 4: Deploy to Cloudflare Workers

# Build project
npm run build

# Deploy
wrangler deploy

Step 5: Configure Domain (Optional)

Go to Cloudflare Dashboard
Navigate to Workers & Pages
Select your worker
Configure custom domain

Database Setup

SQLite (Development)

# Initialize SQLite database
npm run db:init

# Run migrations
npm run db:migrate

# Generate migration (when schema changes)
npm run db:generate

Turso (Production)

# Install Turso CLI
curl -sSfL https://get.tur.so/install.sh | bash

# Create database
turso db create flowcampaign

# Get connection string
turso db show flowcampaign --url

# Create tables
turso db shell flowcampaign < schema.sql

Cloudflare D1 (Alternative)

# Create D1 database
wrangler d1 create flowcampaign

# Apply migrations
wrangler d1 execute flowcampaign --file=migrations/001_initial.sql

Email Provider Configuration

ZeptoMail Setup

Sign up at ZeptoMail
Get API key from dashboard
Verify sending domain
Add API key to environment variables

SMTP Configuration

Common SMTP providers:

Gmail/Google Workspace

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password

SendGrid

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=your-sendgrid-api-key

AWS SES

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=your-ses-smtp-username
SMTP_PASS=your-ses-smtp-password

Environment Variables Reference

Required Variables

Variable	Description	Example
`NODE_ENV`	Environment mode	`development`, `production`
`DATABASE_URL`	Database connection string	`file:./dev.db`
`JWT_SECRET`	JWT signing secret	Random 32+ character string
`APP_URL`	Application URL	`http://localhost:3000`

Email Configuration

Variable	Description	Example
`ZEPTOMAIL_API_KEY`	ZeptoMail API key	`your-zeptomail-api-key`
`SMTP_HOST`	SMTP server host	`smtp.gmail.com`
`SMTP_PORT`	SMTP server port	`587`
`SMTP_USER`	SMTP username	`your-email@gmail.com`
`SMTP_PASS`	SMTP password	`your-app-password`

Optional Configuration

Variable	Description	Default
`APP_PORT`	Application port	`3000`
`SESSION_SECRET`	Session secret	Random string
`UPLOAD_DIR`	File upload directory	`./uploads`
`MAX_FILE_SIZE`	Maximum file size	`10485760` (10MB)
`RATE_LIMIT_WINDOW`	Rate limit window (minutes)	`15`
`RATE_LIMIT_MAX`	Max requests per window	`100`

Development Scripts

Available npm Scripts

{
  "scripts": {
    "dev": "concurrently \"npm run dev:frontend\" \"npm run dev:backend\"",
    "dev:frontend": "vite",
    "dev:backend": "wrangler dev",
    "build": "npm run build:frontend && npm run build:backend",
    "build:frontend": "vite build",
    "build:backend": "wrangler deploy --dry-run",
    "db:migrate": "drizzle-kit migrate",
    "db:generate": "drizzle-kit generate",
    "db:studio": "drizzle-kit studio",
    "test": "vitest",
    "test:e2e": "playwright test",
    "lint": "eslint .",
    "format": "prettier --write .",
    "deploy": "wrangler deploy"
  }
}

Troubleshooting Installation

Common Issues

1. Database Connection Failed

# Check if SQLite is installed
sqlite3 --version

# Check database file permissions
ls -la dev.db

# Reinitialize database
rm dev.db
npm run db:migrate

2. Port Already in Use

# Find process using port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

# Or change port in .env
APP_PORT=3001

3. Missing Dependencies

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear wrangler configuration
rm -rf ~/.wrangler

# Re-login
wrangler login

5. Build Failures

# Clear build artifacts
rm -rf dist build

# Reinstall dependencies
npm ci

# Rebuild
npm run build

Post-Installation Steps

1. Verify Installation

# Check if server is running
curl http://localhost:3000/health

# Check database connectivity
npm run db:check

2. Create Admin User

# Using API
curl -X POST http://localhost:3000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "securepassword",
    "name": "Admin User",
    "role": "admin"
  }'

3. Configure Email Provider

Login to admin panel
Go to Settings > Email Providers
Add your email provider
Test sending

4. Set Up Monitoring

# Install monitoring tools
npm install --save-dev @cloudflare/workers-honeycomb-logger

# Configure logging
echo "HONEYCOMB_API_KEY=your-key" >> .env

Production Checklist

Before deploying to production:

Upgrading

Minor Version Updates

# Pull latest changes
git pull origin main

# Update dependencies
npm update

# Run migrations if needed
npm run db:migrate

# Restart application
npm run build
npm start

Major Version Updates

Check release notes for breaking changes
Backup database
Test upgrade in staging environment
Run migration scripts
Update configuration files
Deploy to production

Uninstallation

Remove Local Installation

# Stop running processes
npm run stop

# Remove database files
rm -f dev.db
rm -rf migrations

# Remove uploads
rm -rf uploads

# Remove node_modules
rm -rf node_modules

# Remove repository
cd ..
rm -rf flowcampaign

Remove Docker Installation

# Stop and remove containers
docker-compose down -v

# Remove images
docker rmi flowcampaign-frontend flowcampaign-backend

# Remove volumes
docker volume prune

Need Help? Check our Troubleshooting Guide or create an issue on GitHub.

FlowCampaign is designed to be easy to install and configure, whether you're setting up for local development or deploying to production.

System Requirements​

Minimum Requirements​

Recommended Requirements​

Installation Methods​

Method 1: Local Development Setup​

Step 1: Clone Repository​

Step 2: Install Dependencies​

Step 3: Configure Environment​

Step 4: Initialize Database​

Step 5: Start Development Server​

Step 6: Verify Installation​

Method 2: Docker Setup​

Step 1: Install Docker​

Step 2: Clone Repository​

Step 3: Configure Docker Environment​

Step 4: Start Docker Containers​

Step 5: Access Application​

Method 3: Production Deployment (Cloudflare Workers)​

Prerequisites​

Step 1: Install Wrangler CLI​

Step 2: Configure Wrangler​

Step 3: Update Production Configuration​

Step 4: Deploy to Cloudflare Workers​

Step 5: Configure Domain (Optional)​

Database Setup​

SQLite (Development)​

Turso (Production)​

Cloudflare D1 (Alternative)​

Email Provider Configuration​

ZeptoMail Setup​

SMTP Configuration​

Gmail/Google Workspace​

SendGrid​

AWS SES​

Environment Variables Reference​

Required Variables​

Email Configuration​

Optional Configuration​

Development Scripts​

Available npm Scripts​

Troubleshooting Installation​

Common Issues​

1. Database Connection Failed​

2. Port Already in Use​

3. Missing Dependencies​

4. Wrangler Login Issues​

5. Build Failures​

Post-Installation Steps​

1. Verify Installation​

2. Create Admin User​

3. Configure Email Provider​

4. Set Up Monitoring​

Production Checklist​

Upgrading​

Minor Version Updates​

Major Version Updates​

Uninstallation​

Remove Local Installation​

Remove Docker Installation​