Deploying a Beaver Habit Tracker App

Beaver is a powerful, open-source habit tracking application designed to help you build and maintain positive habits. Built with modern web technologies, Beaver provides an intuitive interface for tracking daily habits, visualizing progress, and maintaining motivation. Whether you’re looking to develop healthier routines, improve productivity, or establish consistent behaviors, Beaver offers the tools to support your personal growth journey.

Why Beaver Habit Tracker?

Beaver stands out in the habit tracking landscape with its focus on simplicity and effectiveness:

• Open Source: Full transparency and community-driven development with no hidden tracking or data collection
• Privacy First: Your habit data stays on your server—no cloud synchronization or third-party access
• Beautiful Interface: Clean, intuitive UI designed for daily use and motivation
• Habit Streaks: Visual streak tracking to maintain motivation and consistency
• Progress Analytics: Detailed statistics and charts showing your habit completion rates
• Customizable Habits: Create habits with custom frequencies (daily, weekly, specific days)
• Habit Categories: Organize habits by category for better management and tracking
• Reminders: Optional daily reminders to help you stay on track
• Export Data: Export your habit data for analysis or backup purposes
• Lightweight: Minimal resource requirements, perfect for personal servers
• Self-Hosted Control: Complete control over your data and deployment environment

Beaver is ideal for individuals and small teams who want a reliable, privacy-respecting habit tracker without corporate surveillance or subscription fees. With persistent storage on Klutch.sh, your habit data is always safe and accessible.

Prerequisites

Before deploying Beaver Habit Tracker, ensure you have:

• A Klutch.sh account
• A GitHub repository with your Beaver deployment configuration
• Basic familiarity with Docker and Git
• (Optional) PostgreSQL database for production deployments

Deploying Beaver Habit Tracker

1. Create a New Project

   Log in to your Klutch.sh dashboard and create a new project for your Beaver Habit Tracker deployment.

2. Prepare Your Repository

   Create a GitHub repository with the following structure for your Beaver deployment:

   beaver-deploy/
   ├─ Dockerfile
   ├─ .gitignore
   └─ README.md

   Here’s a production-ready Dockerfile for Beaver:

   FROM node:18-alpine
   
   WORKDIR /app
   
   # Install dependencies
   RUN apk add --no-cache git curl
   
   # Clone Beaver repository
   RUN git clone https://github.com/michaeltoohig/beaver.git .
   
   # Install Node.js dependencies
   RUN npm install
   
   # Build the application
   RUN npm run build
   
   # Expose port 3000
   EXPOSE 3000
   
   # Start the application
   CMD ["npm", "start"]

   Commit and push this to your GitHub repository:

   git init
   git add .
   git commit -m "Initial Beaver Habit Tracker deployment"
   git remote add origin https://github.com/yourusername/beaver-deploy.git
   git push -u origin main

3. Create a New App

   In the Klutch.sh dashboard:

   • Click “Create New App”
   • Select your GitHub repository containing the Dockerfile
   • Choose the branch (typically main or master)
   • Klutch.sh will automatically detect the Dockerfile in the root directory

4. Configure Environment Variables

   Set up these environment variables in your Klutch.sh dashboard:

   Variable	Description	Example
   NODE_ENV	Node.js environment	production
   PORT	Application port	3000
   DATABASE_URL	Database connection URL (if using PostgreSQL)	postgres://user:pass@host:5432/beaver
   SESSION_SECRET	Secret key for sessions (generate a random string)	your-random-session-secret-here
   LOG_LEVEL	Logging level	info

   Generating Secrets

   For SESSION_SECRET, generate a secure random string: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

5. Configure Persistent Storage

   Beaver requires persistent storage for your habit data and database files. Add a persistent volume:

   Mount Path	Description	Recommended Size
   /app/data	Application data and SQLite database	5GB

   In the Klutch.sh dashboard:

   • Navigate to your app settings
   • Go to the “Volumes” section
   • Click “Add Volume”
   • Set mount path to /app/data
   • Set size to 5GB (adjust based on your needs)

6. Set Network Configuration

   Configure your app’s network settings:

   • Select traffic type: HTTP
   • Internal port: 3000 (the port Beaver listens on)
   • Klutch.sh will automatically handle HTTPS termination

7. Deploy Your App

   • Review all settings
   • Click “Deploy”
   • Klutch.sh will build the Docker image and start your Beaver instance
   • Wait for the deployment to complete (typically 2-5 minutes)

Initial Setup and Configuration

After deployment completes, access your Beaver instance:

Accessing Beaver

Navigate to your app’s URL: https://example-app.klutch.sh

On first access, you may need to complete the initial setup wizard or create your first account, depending on the Beaver configuration.

Creating Your First Habit

Once logged in, create your first habit:

1. Click “Add Habit” or “New Habit”
2. Enter the habit name (e.g., “Morning Meditation”, “Read for 30 minutes”)
3. Select the habit frequency (daily, weekly, specific days)
4. Add an optional description or category
5. Configure reminders if desired
6. Save the habit

Tracking Daily Habits

Start tracking your habits:

1. Log in to your Beaver instance each day
2. Mark habits as completed by clicking the checkbox or completion button
3. View your current streaks and progress
4. Monitor statistics on the dashboard

Environment Variable Examples

SQLite Configuration (Default)

NODE_ENV=production
PORT=3000
DATABASE_URL=sqlite:///app/data/beaver.db
SESSION_SECRET=your-secure-random-string
LOG_LEVEL=info

PostgreSQL Configuration (Production)

For production deployments with PostgreSQL:

NODE_ENV=production
PORT=3000
DATABASE_URL=postgres://username:password@postgres-host:5432/beaver
SESSION_SECRET=your-secure-random-string
LOG_LEVEL=info
DB_POOL_SIZE=10
DB_POOL_TIMEOUT=5

Sample Code and Getting Started

Creating Habits via API (if available)

# Example: Create a new habit using the Beaver API
curl -X POST https://example-app.klutch.sh/api/habits \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning Exercise",
    "description": "30 minutes of exercise",
    "frequency": "daily",
    "category": "Health"
  }'

Tracking Habit Completion

# Example: Mark a habit as completed for today
curl -X POST https://example-app.klutch.sh/api/habits/{habitId}/complete \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2025-11-30"
  }'

Getting Habit Statistics

# Example: Retrieve habit statistics
curl https://example-app.klutch.sh/api/habits/{habitId}/stats \
  -H "Authorization: Bearer YOUR_TOKEN"

Docker Compose for Local Development

For local testing before deploying to Klutch.sh:

version: '3.8'

services:
  beaver:
    image: node:18-alpine
    working_dir: /app
    volumes:
      - ./beaver:/app
      - beaver_data:/app/data
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - PORT=3000
      - DATABASE_URL=sqlite:///app/data/beaver.db
      - SESSION_SECRET=dev-secret
    command: >
      sh -c "npm install && npm start"
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=beaver
      - POSTGRES_USER=beaver
      - POSTGRES_PASSWORD=beaver_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    restart: unless-stopped

volumes:
  beaver_data:
  postgres_data:

Save as docker-compose.yml and run:

docker-compose up -d

Access Beaver at http://localhost:3000

Backing Up Your Habit Data

Automated Backups

Regular backups of your habit data are essential:

1. Via Klutch.sh Volume Snapshots

   • Use your cloud provider’s volume snapshot feature (if available)
   • Schedule regular snapshots of the /app/data volume

2. Manual Database Backup

   • For SQLite: Copy the /app/data/beaver.db file
   • For PostgreSQL: Use pg_dump to export your database

Backup Commands

# Backup SQLite database (if you have shell access)
sqlite3 /app/data/beaver.db ".backup /app/data/beaver-backup.db"

# Backup PostgreSQL database
pg_dump -h postgres-host -U beaver -d beaver > beaver-backup.sql

Database Setup and Migration

Using PostgreSQL for Production

For larger deployments or team use, PostgreSQL is recommended:

1. Deploy a PostgreSQL instance on Klutch.sh (using the PostgreSQL guide)
2. Note the connection details (host, port, username, password)
3. Update the DATABASE_URL environment variable in Beaver
4. Restart the application for changes to take effect

Migrating from SQLite to PostgreSQL

If you started with SQLite and want to migrate:

# Export from SQLite
sqlite3 /app/data/beaver.db ".dump" > beaver-export.sql

# Import to PostgreSQL
psql -h postgres-host -U beaver -d beaver < beaver-export.sql

Scaling and Performance

Vertical Scaling

As your habit tracking grows or you add team members:

1. Navigate to your app settings in Klutch.sh
2. Increase instance resources (CPU, memory)
3. For production, consider at least 1 CPU core and 512MB RAM

Database Optimization

For PostgreSQL deployments:

DATABASE_POOL_SIZE=20
DATABASE_POOL_TIMEOUT=5
DATABASE_IDLE_TIMEOUT=30000

Caching

Enable caching for better performance:

CACHE_ENABLED=true
CACHE_TTL=3600

Custom Domain Configuration

To use your own domain with Beaver:

1. Navigate to your app’s “Domains” section in Klutch.sh
2. Click “Add Custom Domain”
3. Enter your domain (e.g., habits.yourdomain.com)
4. Configure your DNS provider with a CNAME record:

   habits.yourdomain.com → example-app.klutch.sh

5. Klutch.sh automatically provisions SSL certificates

Security Best Practices

Authentication and Access Control

• Use a strong, unique SESSION_SECRET
• Implement user authentication to protect habit data
• Regularly update dependencies and Beaver version
• Keep sensitive environment variables secure

Network Security

• Always use HTTPS (Klutch.sh provides this automatically)
• Restrict database access to only your Beaver instance
• Use strong database passwords for PostgreSQL
• Monitor access logs for suspicious activity

Data Privacy

• Your habit data never leaves your server
• No external API calls for tracking or analytics
• Regular backups ensure data resilience
• Full control over data retention and deletion

Troubleshooting

Common Issues and Solutions

Issue: App fails to start

Check the deployment logs in Klutch.sh dashboard. Common causes:

• Missing environment variables (especially SESSION_SECRET)
• Database connection issues
• Insufficient disk space in persistent volume

Issue: Habits not saving

Verify:

• Persistent volume is properly mounted at /app/data
• Volume has sufficient free space
• Database is accessible and running

Issue: Slow performance

Solutions:

• Increase instance resources
• Check database connection pool settings
• Optimize PostgreSQL if using it for production
• Clear old habit history if needed

Issue: Cannot connect to PostgreSQL

Troubleshooting:

• Verify DATABASE_URL is correct
• Check that PostgreSQL instance is running
• Ensure network connectivity between Beaver and database
• Verify database credentials and permissions

Upgrading Beaver

To update Beaver to a newer version:

1. Update your Dockerfile to use the latest Beaver code:

   RUN git clone --branch main https://github.com/michaeltoohig/beaver.git .

2. Commit and push to GitHub
3. Klutch.sh will automatically rebuild with the latest version
4. Test the updated version thoroughly before relying on it

Advanced Configuration

Custom Environment Variables

For advanced Beaver configurations:

BEAVER_LOG_LEVEL=debug
BEAVER_SESSION_TIMEOUT=86400
BEAVER_MAX_HABITS_PER_USER=100
BEAVER_ENABLE_NOTIFICATIONS=true
BEAVER_NOTIFICATION_EMAIL=your-email@example.com

Integrations

Connect Beaver with other services:

WEBHOOK_URL=https://your-service.com/webhook
ENABLE_SLACK_NOTIFICATIONS=false
ENABLE_EMAIL_NOTIFICATIONS=true

Additional Resources

• Beaver GitHub Repository - Source code and documentation
• Beaver Issues and Support - Community support and bug reports
• Klutch.sh Getting Started Guide
• Klutch.sh Volumes Documentation
• Klutch.sh Custom Domains Guide
• Node.js Documentation - Language reference
• PostgreSQL Documentation - Database reference

Conclusion

Deploying Beaver Habit Tracker on Klutch.sh provides you with a private, self-hosted habit tracking solution that respects your privacy while supporting your personal growth goals. With persistent storage for your habit data, customizable tracking options, and beautiful analytics, Beaver helps you build and maintain positive habits. Klutch.sh’s managed infrastructure ensures your habit tracker is always available, secure, and performant.

Start your habit tracking journey today by deploying Beaver on Klutch.sh and taking control of your data and personal development.