<img width="300" src="https://github.com/clearflask/clearflask/raw/2.6.2/clearflask-frontend/public/img/clearflask-text.png" alt="ClearFlask">

Open-source Feedback Management Tool.

Alternative to Canny and UserVoice.

Contents

• Managed hosting
• Self hosting
  • Quick start
  • Kubernetes deployment
  • Deploy dependencies
    • Via Docker
    • Via Kubernetes
    • Via AWS
  • Deploy ClearFlask
    • Setup
    • Run
  • Maintenance
    • Migration between Elasticsearch/MySQL
• Contributing
  • Code quality
  • Building
  • Architecture
  • Release
• Security Policy

Managed Hosting

Support our open-source development by choosing cloud hosting with scalable pricing, check us out on our website.

Self Hosting

Quick start

For a quick start using Docker, download the Docker Compose service file as docker-compose.yml, and run the following:

docker-compose --profile with-deps up

Point your browser at http://localhost and create an account using email admin@localhost.

You also want to setup outgoing mail, read the Email section.

If you wish to host it on your domain other than localhost, read the DNS section and then setup SSL/TLS certificates.

Kubernetes deployment

For self-hosting, we provide Kubernetes Helm charts.

Installation

1. Add the Helm repository:

helm repo add clearflask https://clearflask.github.io/clearflask
helm repo update

1. Install dependencies (MySQL + LocalStack):

helm install clearflask-deps clearflask/clearflask-dependencies \
  --set mysql.enabled=true \
  --set localstack.enabled=true

1. Generate secrets and install ClearFlask:

TOKEN_SIGNER=$(openssl rand -base64 172 | tr -d '\n')
CURSOR_KEY=$(openssl rand -base64 16)
SSO_SECRET=$(uuidgen)
CONNECT_TOKEN=$(uuidgen)

helm install clearflask clearflask/clearflask \
  --set global.domain=yourdomain.com \
  --set server.config.searchEngine=READWRITE_MYSQL \
  --set server.secrets.tokenSignerPrivKey="$TOKEN_SIGNER" \
  --set server.secrets.cursorSharedKey="$CURSOR_KEY" \
  --set server.secrets.ssoSecretKey="$SSO_SECRET" \
  --set server.secrets.connectToken="$CONNECT_TOKEN"

1. Access your instance:

kubectl port-forward svc/clearflask-connect 3000:80
# Visit http://localhost:3000

See the Helm Chart documentation for more information.

Replace dependencies

There are several dependencies that you can swap out for ClearFlask:

• AWS DynamoDB or Localstack or API-compatible alternative (ScyllaDB is not fully compatible)
• MinIO or AWS S3 or API-compatible alternative
• One of:
  • MySQL or Aurora
  • ElasticSearch or OpenSearch
• Email service via SMTP or AWS SES

And a few optional:

• Google ReCaptcha
• Let's Encrypt automagic certificate management
• CloudFront as a CDN (Use in front of clearflask-connect)

Via Docker

You can spin up all dependencies via Docker.

Simply add the --profile with-deps to your docker-compose command when starting ClearFlask.

All database content will be persisted to local filesystem under data folder.

Via Kubernetes

Production-ready Helm charts are available:

helm repo add clearflask https://clearflask.github.io/clearflask
helm repo update

helm install clearflask-deps clearflask/clearflask-dependencies \
  --set mysql.enabled=true \
  --set localstack.enabled=true

This deploys:

• MySQL/MariaDB for search and filtering with persistent storage (20Gi default)
• LocalStack for DynamoDB, S3, and SES emulation with persistent storage (10Gi default)
• ElasticSearch (optional) for advanced search with persistent storage (50Gi default)

All databases are persistent by default using PersistentVolumeClaims. See the Helm Chart documentation for configuration options.

Via AWS

For production workload, you will want to spin up these dependencies yourself and point ClearFlask to their endpoints.

IAM access

For AWS services, clearflask-server auto-detects Access Keys using either a configuration property or the default locations. If you are running in EC2 or ECS, keys detection is automated, you just need to create the appropriate IAM role.

AWS DynamoDB

Provide IAM access including create table permission as table is created automatically by ClearFlask on startup.

IAM actions:

• CreateTable
• BatchGetItem
• GetItem
• Query
• BatchWriteItem
• DeleteItem
• PutItem
• UpdateItem

AWS S3

Create a private bucket with IAM access to ClearFlask.

IAM actions:

• ListBucket
• GetObject
• DeleteObject
• PutObject

You can also use an API-compatible alternative service such as Wasabi, MinIO...

ElasticSearch or MySQL

Recommended is AWS ES, give the proper IAM access

IAM actions, all in these categories:

• List
• Read
• Write
• Tagging

Alternatively you can deploy it yourself (cheaper) or host it on Elastic. Or you can choose to use MySQL/Aurora as a cheaper alternative.

AWS SES

In order to setup SES, you need to seek limit increase via AWS support.

Change the config property ...EmailServiceImpl$Config.useService to ses and give the proper IAM access.

IAM actions:

• SendEmail
• SendRawEmail

Alternatively use any other email provider and fill out the SMTP settings

Deploy ClearFlask

ClearFlask consists of two components:

• clearflask-server: Tomcat application for serving API requests
• clearflask-connect: NodeJS for SSR, dynamic cert management and serving static files

Via Kubernetes (Recommended for Production)

No build required - uses pre-built Docker images.

# Add Helm repository
helm repo add clearflask https://clearflask.github.io/clearflask
helm repo update

# Generate required secrets
TOKEN_SIGNER=$(openssl rand -base64 172 | tr -d '\n')
CURSOR_KEY=$(openssl rand -base64 16)
SSO_SECRET=$(uuidgen)
CONNECT_TOKEN=$(uuidgen)

# Install ClearFlask
helm install clearflask clearflask/clearflask \
  --set global.domain=yourdomain.com \
  --set server.config.searchEngine=READWRITE_MYSQL \
  --set server.secrets.tokenSignerPrivKey="$TOKEN_SIGNER" \
  --set server.secrets.cursorSharedKey="$CURSOR_KEY" \
  --set server.secrets.ssoSecretKey="$SSO_SECRET" \
  --set server.secrets.connectToken="$CONNECT_TOKEN"

Features:

• Horizontal Pod Autoscaling
• Zero-downtime rolling updates
• Built-in health checks
• TLS certificate management

For detailed configuration options, deployment scenarios (AWS EKS, GKE, AKS), and troubleshooting, see the Helm Chart documentation.

Via Docker (Quick Start)

Setup

1. Download the Docker Compose service file
2. Run it with docker-compose --profile with-deps up which creates few configuration files in your local directory
3. Carefully read and modify server/config-selfhost.cfg.
4. Carefully read and modify connect/connect.config.json.
5. Adjust the Docker Compose service file to add/remove dependencies if you are hosting them outside of Docker

On the first run, install-specific secrets (VAPID keypair, cursor encryption key, token signing key, SSO key) are generated automatically into server/config-selfhost.cfg. Installs created before this behavior existed share publicly-known default secrets: check your server logs for a SECURITY: warning and regenerate any flagged values using the commands in the config file comments.

Configuration via environment variables

Instead of editing the configuration files, common settings can be set with environment variables on the clearflask-server container. They are applied into config-selfhost.cfg on startup and always take precedence over values in the file. This is useful on platforms without persistent-file editing (Railway, PikaPods, Elestio, ...).

The clearflask-connect container supports: CLEARFLASK_CONNECT_TOKEN, CLEARFLASK_DOMAIN, CLEARFLASK_API_BASE_PATH, CLEARFLASK_LISTEN_PORT, CLEARFLASK_DISABLE_AUTO_FETCH_CERTIFICATE and CLEARFLASK_FORCE_REDIRECT_HTTPS, overriding connect.config.json.

Email

By default, email is configured for AWS SES pointing to your Localstack (which doesn't do anything).

You can choose to setup your own SMTP server or use AWS SES.

Email using SMTP

Change the configuration to SMTP:

• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.useService: smtp

Then you need to gather your SMTP settings and fill out the following:

• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.smtpStrategy: SMTP_TLS (SMTP_TLS, SMTPS, SMTP)
• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.smtpHost: smtp.gmail.com (e.g. smtp.gmail.com)
• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.smtpPort: 587 (587 for SMTP_TLS, 465 for SMTPS, 25 for SMTP)
• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.smtpUser: my.name@gmail.com (e.g. my.name@gmail.com)
• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.smtpPassword: asdfqwerzxcvasdf (To get this working, you need to enable IMAP if not enabled. If you use 2FA, you need to generate an app password and use it here)
• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.emailDisplayName: ClearFlask (e.g. 'ClearFlask for MyCompany')
• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.fromEmailLocalPart: my.name (first part of your email, for my.name@gmail.com, it would be 'my.name')
• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.fromEmailDomainOverride: gmail.com (domain part of your email, for my.name@gmail.com, it would be 'gmail.com')

Email using AWS SES

Change the configuration to SMTP:

• com.smotana.clearflask.core.push.provider.EmailServiceImpl$Config.useService: ses

Then fill out the SES settings:

• com.smotana.clearflask.core.email.AmazonSimpleEmailServiceProvider$Config.region: us-east-1
• com.smotana.clearflask.core.email.AmazonSimpleEmailServiceProvider$Config.serviceEndpoint: (Leave blank, unless you need to override)

DNS

By default, everything is assumed to be on localhost. If you wish to host your portal on yoursite.com or 192.168.1.123, set the following properties:

• connect.config.json:parentDomain: yoursite.com
• `config-selfhost.cfg:com.