Skip to content
Klutch.sh Docs

Deploying AppFlowy

Introduction

AppFlowy is an open-source alternative to Notion, built with Flutter and Rust. It’s a powerful workspace and productivity platform that allows you to organize your notes, tasks, wikis, and databases in one place. AppFlowy emphasizes data privacy, customization, and extensibility, making it an excellent choice for individuals and teams who want control over their productivity tools.

AppFlowy features:

  • Rich Text Editor: Create beautiful documents with markdown support
  • Kanban Boards: Organize tasks and projects visually
  • Calendar Views: Schedule and track events
  • Database Management: Build custom databases with multiple views
  • Offline-First: Work seamlessly without an internet connection
  • Self-Hosted: Full control over your data and privacy
  • Customizable: Theme and extend with plugins

This comprehensive guide walks you through deploying AppFlowy on Klutch.sh using Docker, including detailed installation steps, sample configurations, and production-ready best practices for persistent storage.

Prerequisites

Before you begin, ensure you have the following:

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your AppFlowy deployment project:

Terminal window
mkdir appflowy-klutch
cd appflowy-klutch
git init

Step 2: Create the Dockerfile

Create a Dockerfile in your project root directory. This will define your AppFlowy container configuration:

FROM ghcr.io/appflowy-io/appflowy_web:latest


# Set working directory
WORKDIR /app


# Optional: Add custom configuration
# COPY ./config /app/config


# Expose the default AppFlowy port
EXPOSE 8080


# The base image already has the CMD configured
# CMD is typically: ["./appflowy_web"]

Note: AppFlowy provides official Docker images that are pre-configured and ready to use. The example above uses the web version of AppFlowy.

Step 3: (Optional) Create a Configuration File

You can create a configuration file for AppFlowy settings. Create a file named appflowy.conf:

# appflowy.conf - AppFlowy configuration


# Server settings
HOST=0.0.0.0
PORT=8080


# Database settings (if using external database)
# DATABASE_URL=postgresql://user:password@host:port/dbname


# Storage settings
STORAGE_PATH=/app/data

If you create a configuration file, add a COPY command in your Dockerfile to include it:

COPY ./appflowy.conf /app/appflowy.conf

Step 4: Create Environment Variables File (Optional)

Create a .env.example file to document the environment variables your deployment might need:

Terminal window
# .env.example - Environment variables template


# Application settings
APPFLOWY_ENV=production
APPFLOWY_PORT=8080


# Security
APPFLOWY_SECRET_KEY=your-secret-key-here


# Optional: Database configuration
# DATABASE_URL=postgresql://username:password@host:port/database

Important: Never commit actual secrets to your repository. This file is just a template.

Step 5: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your AppFlowy setup locally:

Terminal window
# Build the Docker image
docker build -t my-appflowy .


# Run the container
docker run -d \
  --name appflowy-test \
  -p 8080:8080 \
  -v appflowy-data:/app/data \
  my-appflowy


# Check if it's running
docker ps


# View logs
docker logs appflowy-test


# Access AppFlowy at http://localhost:8080


# Stop and remove the test container when done
docker stop appflowy-test
docker rm appflowy-test

Step 6: Push to GitHub

Commit your Dockerfile and configuration files to your GitHub repository:

Terminal window
git add Dockerfile appflowy.conf .env.example
git commit -m "Add AppFlowy Docker configuration"
git remote add origin https://github.com/yourusername/appflowy-klutch.git
git push -u origin main

Deploying Without a Dockerfile

Klutch.sh uses Nixpacks to automatically detect and build your application. However, since AppFlowy is primarily distributed as pre-built Docker images, we recommend using the Dockerfile approach for AppFlowy deployments to ensure you’re using the official, tested images.

If you want to build from source:

  1. Clone the AppFlowy repository and push it to GitHub
  2. Log in to Klutch.sh
  3. Create a new project
  4. Create a new app:
    • Select your GitHub repository and branch
    • Select HTTP as the traffic type
    • Set the internal port to 8080
    • Add environment variables as needed

Note: If you need to customize the start or build command, you can set environment variables like START_COMMAND or BUILD_COMMAND for Nixpacks.

Klutch.sh will automatically detect a Dockerfile in your repository’s root directory. This is the recommended approach for AppFlowy deployments.

Follow these steps to deploy AppFlowy on Klutch.sh with persistent storage:

    1. Log in to Klutch.sh

      Navigate to klutch.sh/app and sign in to your account.

    2. Create a New Project

      Go to Create Project and give your project a meaningful name (e.g., “AppFlowy Workspace”).

    3. Create a New App

      Navigate to Create App and configure the following settings:

    4. Select Your Repository

      • Choose GitHub as your Git source
      • Select the repository containing your Dockerfile
      • Choose the branch you want to deploy (usually main or master)

    5. Configure Traffic Type

      • Traffic Type: Select HTTP (AppFlowy web interface uses HTTP/HTTPS)
      • Internal Port: Set to 8080 (the port your container listens on)

    6. Set Environment Variables

      Add the following environment variables for your AppFlowy configuration:

      • APPFLOWY_ENV: Set to production
      • APPFLOWY_SECRET_KEY: A strong secret key for security (use a secure password generator)
      • Add any other custom environment variables your setup requires

      Security Note: Always use strong, unique secret keys for production deployments.

    7. Attach a Persistent Volume

      This is critical for ensuring your workspace data persists across deployments and restarts:

      • In the Volumes section, click “Add Volume”
      • Mount Path: Enter /app/data (this is where AppFlowy stores workspace data)
      • Size: Choose an appropriate size based on your expected data volume (e.g., 5GB, 10GB, or more)

      Important: AppFlowy requires persistent storage to maintain your notes, databases, and other workspace data between container restarts.

    8. Configure Additional Settings

      • Region: Select the region closest to your users for optimal latency
      • Compute Resources: Choose CPU and memory based on your workload (minimum 512MB RAM recommended)
      • Instances: Start with 1 instance (you can scale up later based on usage)

    9. Deploy Your Application

      Click “Create” to start the deployment. Klutch.sh will:

      • Automatically detect your Dockerfile in the repository root
      • Build the Docker image
      • Attach the persistent volume
      • Start your AppFlowy container
      • Assign a URL for external access

    10. Access Your AppFlowy Instance

      Once deployment is complete, you’ll receive a URL like example-app.klutch.sh. Navigate to this URL in your browser to access your AppFlowy workspace.

Getting Started with AppFlowy

Once your AppFlowy instance is deployed and running, you can start using it:

Creating Your First Workspace

  1. Open your deployed AppFlowy URL (example-app.klutch.sh) in a browser
  2. Create your account or workspace
  3. Start creating documents, databases, and organizing your content

Sample Document Structure

Here’s a basic document structure you can create in AppFlowy:

Project Management Workspace

📁 Projects
  ├── 📄 Project Alpha
  │   ├── Overview
  │   ├── Tasks (Kanban Board)
  │   └── Timeline (Calendar)
  ├── 📄 Project Beta
  └── 📊 Resource Database

Using AppFlowy Features

Creating a Document:

  1. Click “New Page” or ”+”
  2. Choose “Document” as the page type
  3. Start writing with rich text formatting and markdown support

Creating a Database:

  1. Click “New Page” or ”+”
  2. Choose “Database” or “Board” for Kanban view
  3. Add properties and customize views

Keyboard Shortcuts:

  • Ctrl/Cmd + N: New page
  • Ctrl/Cmd + K: Quick search
  • /: Trigger command menu
  • Ctrl/Cmd + /: Toggle sidebar

Production Best Practices

Security Recommendations

  • Use Strong Secrets: Never use default or weak secret keys in production. Generate strong, random keys using a password manager or cryptographic tools.
  • Environment Variables: Store all sensitive credentials as environment variables in Klutch.sh, never in your Dockerfile or repository.
  • HTTPS: Klutch.sh provides HTTPS by default, ensuring encrypted connections to your AppFlowy instance.
  • Regular Backups: Implement a backup strategy for your persistent volume data.
  • Access Control: Consider implementing authentication layers or IP restrictions for sensitive workspaces.

Performance Optimization

  • Resource Monitoring: Monitor your AppFlowy instance’s CPU and memory usage through Klutch.sh dashboard.
  • Volume Size: Allocate sufficient storage for your expected data growth.
  • Scaling: If you experience high traffic, consider scaling up compute resources or adding more instances.
  • Caching: Configure appropriate caching headers for static assets.

Data Management

  • Persistent Volumes: Always use persistent volumes for production deployments to prevent data loss.
  • Regular Maintenance: Periodically check disk usage and clean up unnecessary data.
  • Database Backups: If using an external database, implement automated backup schedules.

Monitoring

Monitor your AppFlowy deployment for:

  • Response times and page load speeds
  • CPU and memory utilization
  • Disk space usage on persistent volumes
  • Application errors and logs (viewable in Klutch.sh dashboard)
  • User activity and concurrent connections

Troubleshooting

Cannot Access AppFlowy

  • Verify that your deployment is running in the Klutch.sh dashboard
  • Check that the internal port is set to 8080
  • Ensure HTTP is selected as the traffic type
  • Review deployment logs for any startup errors

Data Not Persisting

  • Verify that the persistent volume is correctly attached at /app/data
  • Check that the volume has sufficient space allocated
  • Ensure the volume mount path matches AppFlowy’s data directory

Performance Issues

  • Review resource utilization in the Klutch.sh dashboard
  • Consider increasing CPU and memory allocation
  • Check if disk I/O is a bottleneck (upgrade volume if needed)
  • Optimize large documents or databases

Configuration Problems

  • Verify all environment variables are set correctly in Klutch.sh
  • Check Docker logs for configuration errors
  • Ensure the Dockerfile is correctly formatted and builds locally

Additional Resources

Conclusion

Deploying AppFlowy to Klutch.sh with Docker provides a robust, self-hosted productivity solution with full control over your data. By following this guide, you’ve set up a production-ready AppFlowy instance with persistent storage, proper security configurations, and the ability to scale as your needs grow. Your workspace is now ready to support your productivity and collaboration needs with the privacy and customization benefits of self-hosting.