Skip to content
Klutch.sh Docs

Deploying Flatnotes

Introduction

Flatnotes is a lightweight, self-hosted note-taking application designed for simplicity and speed. Built with a minimalist approach, Flatnotes provides a clean, distraction-free interface for managing your notes in markdown format. It’s perfect for developers, writers, and anyone who values privacy and wants full control over their note-taking data.

Key features of Flatnotes include:

  • Markdown Support: Write notes in markdown with live preview
  • Fast and Lightweight: Built for speed with minimal resource requirements
  • Self-Hosted: Full control over your data and privacy
  • Simple Interface: Clean, intuitive UI focused on writing
  • File-Based Storage: Notes stored as simple markdown files on disk

Deploying Flatnotes on Klutch.sh provides you with a reliable, scalable platform for your personal note-taking system, with automated deployments from GitHub and persistent storage for your notes.

Prerequisites

Before you begin, ensure you have:

  • A Klutch.sh account (sign up here)
  • A GitHub account with a repository for your Flatnotes deployment
  • Basic understanding of Docker and containerization
  • Familiarity with markdown syntax (helpful but not required)

Getting Started with Flatnotes

Flatnotes is designed to be deployed as a Docker container, making it ideal for deployment on Klutch.sh. The application stores notes as markdown files in a persistent storage directory, ensuring your data is preserved across deployments.

Understanding Flatnotes Architecture

  • Port: Flatnotes runs on port 8080 by default
  • Storage: Requires persistent storage mounted at /data for note storage
  • Authentication: Supports optional password protection via environment variables
  • File Format: All notes are stored as plain markdown files

Deploying Flatnotes with a Dockerfile

Klutch.sh automatically detects and uses a Dockerfile when present in your repository’s root directory. Follow these steps to deploy Flatnotes:

Step 1: Create Your Repository

    1. Create a new GitHub repository for your Flatnotes deployment

    2. Clone the repository to your local machine:

      Terminal window
      git clone https://github.com/yourusername/flatnotes-deploy.git
      cd flatnotes-deploy

Step 2: Create the Dockerfile

    Create a Dockerfile in the root of your repository with the following content:

    # Use the official Flatnotes image
    FROM dullage/flatnotes:latest
    

    # Expose the port Flatnotes runs on
    EXPOSE 8080
    

    # The /data directory will be used for persistent storage
    VOLUME ["/data"]
    

    # Start Flatnotes
    CMD ["python", "-m", "flatnotes"]

    This Dockerfile uses the official Flatnotes image and exposes port 8080. The /data directory is designated as a volume for persistent note storage.

Step 3: Optional Configuration Files

    You can create a .env.example file to document available environment variables:

    Terminal window
    # Optional: Set a password for authentication
    # FLATNOTES_AUTH_TYPE=password
    # FLATNOTES_PASSWORD=your-secure-password
    

    # Optional: Set the title of your Flatnotes instance
    # FLATNOTES_TITLE=My Notes
    

    # Optional: Enable search functionality
    # FLATNOTES_SEARCH_ENABLED=true

    Note: Don’t commit actual secrets to your repository. Set these as environment variables in Klutch.sh.

Step 4: Push to GitHub

    Terminal window
    git add Dockerfile
    # If you created .env.example, add it too
    # git add .env.example
    git commit -m "Add Flatnotes Dockerfile and configuration"
    git push origin main

Step 5: Deploy on Klutch.sh

    1. Log in to Klutch.sh Dashboard
    2. Create a new project and give it a descriptive name (e.g., “Flatnotes”)
    3. Create a new app within your project:
      • Repository: Select your Flatnotes GitHub repository
      • Branch: Choose your deployment branch (usually main)
      • Traffic Type: Select HTTP (Flatnotes is a web application)
      • Internal Port: Set to 8080 (the port Flatnotes listens on)
      • Region: Choose your preferred deployment region
      • Compute Resources: Select based on your expected usage (start with the smallest tier)
      • Instances: Start with 1 instance

Step 6: Configure Persistent Storage

    Flatnotes requires persistent storage to save your notes between deployments:

    1. In your app settings, navigate to the Volumes section
    2. Click Add Volume
    3. Configure the volume:
      • Mount Path: /data
      • Size: Start with 1GB (adjust based on your needs)
    4. Click Create to attach the volume

    This ensures your notes are preserved across deployments and restarts.

Step 7: Set Environment Variables (Optional)

    If you want to enable authentication or customize your Flatnotes instance:

    1. Navigate to the Environment Variables section in your app settings
    2. Add the following variables as needed:
      • FLATNOTES_AUTH_TYPE: Set to password to enable password protection
      • FLATNOTES_PASSWORD: Your secure password (mark as secret)
      • FLATNOTES_TITLE: Custom title for your notes app
      • FLATNOTES_SEARCH_ENABLED: Set to true to enable search

    Security Note: Always mark sensitive variables like passwords as secrets in the Klutch.sh dashboard.

Step 8: Deploy

    Click Create to deploy your Flatnotes instance. Klutch.sh will:

    1. Detect your Dockerfile automatically
    2. Build the Docker image
    3. Deploy your container with the specified configuration
    4. Make your app available at a URL like example-app.klutch.sh

Accessing Your Flatnotes Instance

Once deployed, your Flatnotes instance will be available at the URL provided by Klutch.sh (e.g., your-flatnotes-app.klutch.sh). If you enabled password authentication, you’ll be prompted to log in when you first access the app.

Sample Dockerfile Variations

Minimal Dockerfile

For the simplest deployment:

FROM dullage/flatnotes:latest
EXPOSE 8080

Klutch.sh will handle the rest automatically.

Advanced Dockerfile with Health Check

For production deployments with health monitoring:

FROM dullage/flatnotes:latest


# Install curl for health checks (if not already present)
RUN apk add --no-cache curl || apt-get update && apt-get install -y curl


# Expose the application port
EXPOSE 8080


# Add a health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:8080/ || exit 1


# Volume for persistent data
VOLUME ["/data"]


# Start the application
CMD ["python", "-m", "flatnotes"]

Environment Variables Reference

Flatnotes supports several environment variables for customization:

VariableDescriptionDefaultExample
FLATNOTES_AUTH_TYPEAuthentication methodnonepassword
FLATNOTES_PASSWORDPassword for authentication-your-secure-password
FLATNOTES_TITLEApplication titleFlatnotesMy Personal Notes
FLATNOTES_SEARCH_ENABLEDEnable search functionalityfalsetrue
FLATNOTES_TOTP_KEYTOTP key for 2FA--

Set these variables in the Klutch.sh dashboard under your app’s environment variables section.

Persistent Storage Best Practices

Storage Requirements

  • Minimum: 1GB for basic note-taking
  • Recommended: 5GB for active users with many notes
  • Heavy Usage: 10GB+ for large note collections with attachments

Backup Considerations

Your notes are stored in the /data directory. Consider:

  • Regular backups of your persistent volume
  • Version control for critical notes
  • Export functionality for disaster recovery

Storage Path Structure

Flatnotes organizes notes in the following structure within /data:

/data/
  └── notes/
      ├── note1.md
      ├── note2.md
      └── subfolder/
          └── note3.md

Customizing Your Deployment

Custom Domain

To use a custom domain with your Flatnotes instance:

  1. Navigate to your app settings in Klutch.sh
  2. Go to the Domains section
  3. Add your custom domain
  4. Configure your DNS settings as instructed
  5. Klutch.sh will automatically provision SSL certificates

For more details, see the Custom Domains Guide.

Scaling Considerations

Flatnotes is designed for single-user or small team usage. For optimal performance:

  • Start with minimal compute resources
  • Monitor resource usage in the Klutch.sh dashboard
  • Scale up if you notice performance issues
  • One instance is typically sufficient for personal use

Troubleshooting Common Issues

Issue: Notes Not Persisting

Solution: Ensure the persistent volume is correctly mounted to /data:

  • Check volume configuration in Klutch.sh dashboard
  • Verify the mount path is exactly /data
  • Redeploy the app after adding the volume

Issue: Can’t Access the Application

Solution: Verify your network settings:

  • Ensure traffic type is set to HTTP
  • Confirm internal port is set to 8080
  • Check that the deployment completed successfully
  • Review application logs for errors

Issue: Authentication Not Working

Solution: Check your environment variables:

  • Verify FLATNOTES_AUTH_TYPE is set to password
  • Ensure FLATNOTES_PASSWORD is configured
  • Confirm variables are marked as secrets if sensitive
  • Restart the application after changing variables

Monitoring and Maintenance

Application Logs

Monitor your Flatnotes instance through the Klutch.sh dashboard:

  1. Navigate to your app
  2. Click on Logs to view real-time application logs
  3. Look for errors or warnings
  4. Use logs for debugging and troubleshooting

Health Monitoring

To ensure your Flatnotes instance is running smoothly:

  • Monitor CPU and memory usage in the dashboard
  • Set up uptime monitoring for the application URL
  • Check logs regularly for any issues
  • Keep the Flatnotes Docker image updated

Updates and Maintenance

To update Flatnotes to the latest version:

  1. Update the image tag in your Dockerfile (or keep latest for automatic updates)
  2. Push changes to GitHub
  3. Klutch.sh will automatically rebuild and redeploy your app

Security Best Practices

Authentication

For production deployments:

  • Always enable password authentication using FLATNOTES_AUTH_TYPE=password
  • Use a strong, unique password stored as a secret in Klutch.sh
  • Consider enabling TOTP-based 2FA for additional security

Network Security

  • Keep your Flatnotes instance private if not needed publicly
  • Use custom domains with SSL/TLS (automatically provided by Klutch.sh)
  • Review access logs regularly

Data Security

  • Regular backups of your persistent volume
  • Keep the Flatnotes image updated for security patches
  • Never commit secrets or passwords to your repository
  • Use environment variables for all sensitive configuration

Advanced Configuration

Using Nixpacks for Customization

While this guide focuses on Dockerfile deployment, if you need to customize build or start commands through Nixpacks, you can set environment variables:

  • BUILD_COMMAND: Custom build command (not typically needed for Flatnotes)
  • START_COMMAND: Custom start command if you need to override the default

However, the Dockerfile approach is recommended for Flatnotes as it provides the most reliable deployment.

Resources

Conclusion

Deploying Flatnotes on Klutch.sh gives you a fast, private, and reliable note-taking solution with the benefits of automated deployments, persistent storage, and easy scaling. The combination of Flatnotes’ simplicity and Klutch.sh’s robust infrastructure makes it an ideal setup for anyone looking to self-host their notes securely.

With this guide, you now have everything you need to:

  • Deploy Flatnotes using Docker on Klutch.sh
  • Configure persistent storage for your notes
  • Secure your instance with authentication
  • Customize and maintain your deployment

Start taking notes with confidence, knowing your data is under your control and deployed on reliable infrastructure.