Skip to content
Klutch.sh Docs

Deploying a Bicimon App

Bicimon is an innovative, open-source bicycle ride tracking and management application designed for cyclists of all levels. Built with modern web technologies, Bicimon allows you to log your cycling adventures, track performance metrics, analyze routes, and share your cycling journey with the community. Whether you’re a casual commuter, weekend warrior, or competitive cyclist, Bicimon provides powerful tools to monitor your progress, optimize your training, and celebrate your achievements.

Why Bicimon?

Bicimon stands out in the cycling tracker landscape with its comprehensive features and cyclist-friendly design:

  • Ride Logging: Easily record cycling activities with GPS tracking, duration, distance, and elevation data
  • Performance Analytics: Track speed, average pace, elevation gain, and other key cycling metrics
  • Route Management: Save favorite routes, create new routes, and discover popular cycling paths
  • Training Insights: Monitor training progress over time with detailed statistics and visualizations
  • Social Features: Share rides with friends, join cycling communities, and celebrate milestones
  • Data Export: Export your cycling data in multiple formats for analysis and backup
  • Multi-User Support: Create accounts for multiple cyclists and track individual or group activities
  • Bike Management: Track multiple bikes with individual maintenance logs and statistics
  • Weather Integration: View weather conditions during rides and correlate performance with weather
  • Device Integration: Support for popular cycling apps and GPS devices
  • Privacy First: Your cycling data stays on your server with complete control
  • Open Source: MIT licensed with active community development and support

Bicimon is perfect for cycling enthusiasts, training groups, and organizations that want complete control over cycling data. With persistent storage on Klutch.sh, your ride history and performance metrics are always safe, searchable, and accessible.

Prerequisites

Before deploying Bicimon, ensure you have:

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

Deploying Bicimon

  1. Create a New Project

    Log in to your Klutch.sh dashboard and create a new project for your Bicimon deployment.

  2. Prepare Your Repository

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

    bicimon-deploy/
    ├─ Dockerfile
    ├─ .env.example
    ├─ docker-entrypoint.sh
    ├─ .gitignore
    └─ README.md

    Here’s a production-ready Dockerfile for Bicimon:

    FROM node:18-alpine
    

    WORKDIR /app
    

    # Install dependencies
    RUN apk add --no-cache \
        git \
        curl \
        build-essential \
        python3
    

    # Clone Bicimon repository
    RUN git clone https://github.com/bicimon/bicimon.git .
    

    # Install Node.js dependencies
    RUN npm install --production
    

    # Build the application
    RUN npm run build
    

    # Create necessary directories
    RUN mkdir -p /app/data /app/logs
    

    # Expose port 3000
    EXPOSE 3000
    

    # Copy entrypoint script
    COPY docker-entrypoint.sh /
    RUN chmod +x /docker-entrypoint.sh
    

    # Health check
    HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
      CMD curl -f http://localhost:3000/health || exit 1
    

    # Start application
    CMD ["/docker-entrypoint.sh"]

    Create a docker-entrypoint.sh script for initialization:

    #!/bin/sh
    set -e
    

    echo "Starting Bicimon..."
    

    # Run database migrations if needed
    if [ "$DATABASE_MIGRATE" = "true" ]; then
      echo "Running database migrations..."
      npm run migrate || true
    fi
    

    # Start the application
    npm start

    Create a .env.example file:

    Terminal window
    # Application
    NODE_ENV=production
    PORT=3000
    LOG_LEVEL=info
    

    # Database
    DATABASE_URL=postgresql://bicimon:password@localhost:5432/bicimon
    DATABASE_MIGRATE=true
    

    # Session and Security
    SESSION_SECRET=your-secure-session-secret
    JWT_SECRET=your-jwt-secret
    

    # API Configuration
    API_RATE_LIMIT=100
    API_RATE_WINDOW=900
    

    # Features
    ENABLE_SOCIAL_FEATURES=true
    ENABLE_WEATHER_INTEGRATION=true
    ENABLE_DEVICE_SYNC=true

    Commit and push to your GitHub repository:

    Terminal window
    git init
    git add .
    git commit -m "Initial Bicimon deployment"
    git remote add origin https://github.com/yourusername/bicimon-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:

    VariableDescriptionExample
    NODE_ENVNode.js environmentproduction
    PORTApplication port3000
    DATABASE_URLDatabase connection stringpostgresql://user:pass@host:5432/bicimon
    DATABASE_MIGRATERun migrations on startuptrue
    SESSION_SECRETSecret for session management (generate a random string)your-secure-session-secret
    JWT_SECRETSecret for JWT tokens (generate a random string)your-jwt-secret
    LOG_LEVELLogging level (debug, info, warn, error)info
    API_RATE_LIMITRate limit requests per window100
    ENABLE_SOCIAL_FEATURESEnable ride sharing and community featurestrue
    ENABLE_WEATHER_INTEGRATIONEnable weather data integrationtrue

  5. Configure Persistent Storage

    Bicimon requires persistent storage for ride data and application files. Add persistent volumes:

    Mount PathDescriptionRecommended Size
    /app/dataRide data, GPS tracks, and media100GB
    /app/logsApplication logs10GB

    In the Klutch.sh dashboard:

    • Navigate to your app settings
    • Go to the “Volumes” section
    • Click “Add Volume” for each mount path
    • Set mount paths and sizes as specified above

  6. Set Network Configuration

    Configure your app’s network settings:

    • Select traffic type: HTTP
    • Internal port: 3000 (the Bicimon application port)
    • 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 Bicimon instance
    • Wait for the deployment to complete (typically 3-5 minutes)

Initial Setup and Configuration

After deployment completes, access your Bicimon instance:

Accessing Bicimon

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

You’ll see the Bicimon home page where you can sign up for an account or log in if you already have one.

Creating Your Account

  1. Click “Sign Up” or “Register”
  2. Enter your email address and create a secure password
  3. Complete your profile:
    • Display name (cycling alias)
    • Home location
    • Cycling interests (mountain biking, road cycling, commuting, etc.)
  4. Verify your email address
  5. Set up your first bike

Recording Your First Ride

Once your account is set up:

  1. Click “Log Ride” or “New Activity”
  2. Enter ride details:
    • Date and start time
    • Duration
    • Distance (or let GPS calculate it)
    • Bike used
    • Route name and description
  3. Add GPS track if available
  4. Optionally add weather conditions and notes
  5. Save the ride

Managing Your Bikes

Set up and track your bicycles:

  1. Go to “My Bikes” or “Equipment” in your profile
  2. Click “Add Bike”
  3. Enter bike details:
    • Bike name (e.g., “Road Bike”, “Mountain Bike”)
    • Type (road, mountain, hybrid, cruiser, etc.)
    • Manufacturer and model
    • Purchase date
    • Initial mileage
  4. Track maintenance history
  5. Monitor tire wear and component lifespan

Environment Variable Examples

Basic Configuration

Terminal window
NODE_ENV=production
PORT=3000
LOG_LEVEL=info
SESSION_SECRET=your-secure-session-secret-here
JWT_SECRET=your-jwt-secret-here
API_RATE_LIMIT=100
API_RATE_WINDOW=900

PostgreSQL Configuration (Production)

For production deployments with PostgreSQL:

Terminal window
NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://bicimon:secure_password@postgres-host:5432/bicimon
DATABASE_MIGRATE=true
SESSION_SECRET=your-secure-session-secret
JWT_SECRET=your-jwt-secret
LOG_LEVEL=info
ENABLE_SOCIAL_FEATURES=true
ENABLE_WEATHER_INTEGRATION=true
API_RATE_LIMIT=500

Advanced Configuration

For fine-tuned control:

Terminal window
CACHE_ENABLED=true
CACHE_TTL=3600
ENABLE_DEVICE_SYNC=true
ENABLE_STRAVA_IMPORT=true
ENABLE_GPXFILE_UPLOAD=true
MAX_FILE_UPLOAD_SIZE=104857600
GPS_PRECISION=6

Sample Code and Getting Started

Recording a Ride Programmatically

Terminal window
# Create a new ride via API
curl -X POST https://example-app.klutch.sh/api/rides \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Morning Commute",
    "description": "Beautiful weather for a ride",
    "startTime": "2025-11-30T06:30:00Z",
    "duration": 1800,
    "distance": 15.5,
    "elevationGain": 245,
    "bikeId": "bike-123",
    "routeId": "route-456"
  }'

Retrieving Ride Statistics

Terminal window
# Get monthly statistics
curl https://example-app.klutch.sh/api/stats/monthly \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -G \
  --data-urlencode "year=2025" \
  --data-urlencode "month=11"


# Get bike-specific statistics
curl "https://example-app.klutch.sh/api/bikes/bike-123/stats" \
  -H "Authorization: Bearer YOUR_API_TOKEN"


# Get all rides for a date range
curl "https://example-app.klutch.sh/api/rides" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -G \
  --data-urlencode "startDate=2025-01-01" \
  --data-urlencode "endDate=2025-12-31"

Importing GPS Data

Terminal window
# Upload a GPX file
curl -X POST https://example-app.klutch.sh/api/rides/import \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "gpxFile=@ride.gpx" \
  -F "bikeId=bike-123"

JavaScript Example - Creating a Ride

const API_TOKEN = "your-api-token";
const BICIMON_URL = "https://example-app.klutch.sh";


async function recordRide(rideData) {
  try {
    const response = await fetch(`${BICIMON_URL}/api/rides`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${API_TOKEN}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        title: rideData.title,
        description: rideData.description,
        startTime: new Date(rideData.startTime).toISOString(),
        duration: rideData.duration,
        distance: rideData.distance,
        elevationGain: rideData.elevationGain,
        bikeId: rideData.bikeId,
        gpsTrack: rideData.gpsTrack || null
      })
    });


    if (response.ok) {
      const ride = await response.json();
      console.log("Ride recorded successfully:", ride);
      return ride;
    } else {
      console.error("Error recording ride:", response.statusText);
    }
  } catch (error) {
    console.error("Network error:", error);
  }
}


// Usage
recordRide({
  title: "Evening Ride",
  description: "Scenic route through the park",
  startTime: "2025-11-30T18:00:00",
  duration: 1500,
  distance: 12.3,
  elevationGain: 150,
  bikeId: "bike-123"
});

Python Example - Analyzing Ride Data

import requests
from datetime import datetime, timedelta


API_TOKEN = "your-api-token"
BICIMON_URL = "https://example-app.klutch.sh"


def get_monthly_stats(year, month):
    """Retrieve monthly cycling statistics"""
    headers = {"Authorization": f"Bearer {API_TOKEN}"}
    params = {"year": year, "month": month}


    response = requests.get(
        f"{BICIMON_URL}/api/stats/monthly",
        headers=headers,
        params=params
    )


    if response.status_code == 200:
        stats = response.json()
        print(f"Monthly Statistics for {month}/{year}:")
        print(f"Total Rides: {stats.get('rideCount')}")
        print(f"Total Distance: {stats.get('totalDistance')} km")
        print(f"Total Duration: {stats.get('totalDuration')} minutes")
        print(f"Average Speed: {stats.get('averageSpeed')} km/h")
        print(f"Total Elevation Gain: {stats.get('totalElevationGain')} m")
        return stats
    else:
        print(f"Error: {response.status_code}")
        return None


def get_bike_stats(bike_id):
    """Get statistics for a specific bike"""
    headers = {"Authorization": f"Bearer {API_TOKEN}"}


    response = requests.get(
        f"{BICIMON_URL}/api/bikes/{bike_id}/stats",
        headers=headers
    )


    if response.status_code == 200:
        stats = response.json()
        print(f"Bike Statistics:")
        print(f"Total Distance: {stats.get('totalDistance')} km")
        print(f"Total Rides: {stats.get('rideCount')}")
        print(f"Last Ridden: {stats.get('lastRideDate')}")
        return stats
    else:
        print(f"Error: {response.status_code}")
        return None


# Usage
get_monthly_stats(2025, 11)
get_bike_stats("bike-123")

Docker Compose for Local Development

For local testing before deploying to Klutch.sh:

version: '3.8'


services:
  bicimon:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
      - PORT=3000
      - DATABASE_URL=postgresql://bicimon:bicimon_password@postgres:5432/bicimon
      - SESSION_SECRET=dev-session-secret
      - JWT_SECRET=dev-jwt-secret
      - LOG_LEVEL=debug
      - DATABASE_MIGRATE=true
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    restart: unless-stopped


  postgres:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=bicimon
      - POSTGRES_USER=bicimon
      - POSTGRES_PASSWORD=bicimon_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "bicimon"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped


volumes:
  postgres_data:

Save as docker-compose.yml and run:

Terminal window
docker-compose up -d

Access Bicimon at http://localhost:3000

Backing Up Your Ride Data

Persistent Volume Backups

Regular backups are essential for your cycling history:

  1. Via Klutch.sh Volume Snapshots

    • Use your cloud provider’s volume snapshot feature
    • Schedule regular snapshots of both /app/data and database volumes

  2. Manual Database Backup

    • Export your ride data regularly
    • Backup configuration files

Backup Procedures

Terminal window
# Backup PostgreSQL database
pg_dump -h postgres-host -U bicimon -d bicimon > bicimon-backup.sql


# Restore from backup
psql -h postgres-host -U bicimon -d bicimon < bicimon-backup.sql


# Create a tarball of ride data
tar -czf bicimon-data-backup.tar.gz /app/data/

Database Setup and Migration

Using PostgreSQL for Production

For production deployments with PostgreSQL:

  1. Deploy a PostgreSQL instance on Klutch.sh or use an external database
  2. Note the connection details (host, port, username, password, database name)
  3. Update the DATABASE_URL environment variable in Bicimon
  4. Set DATABASE_MIGRATE=true to run migrations on startup
  5. Restart the application for changes to take effect

Database Initialization

On first deployment, Bicimon automatically initializes the database schema:

Terminal window
# Manual database initialization (if needed)
npm run migrate

Using MySQL as Alternative

If you prefer MySQL instead of PostgreSQL:

Terminal window
DATABASE_URL=mysql://bicimon:password@localhost:3306/bicimon

Scaling and Performance

Vertical Scaling

For active cycling communities:

  1. Navigate to your app settings in Klutch.sh
  2. Increase instance resources:
    • Minimum 2 CPU cores for production
    • Minimum 2GB RAM
  3. Increase volume sizes to accommodate ride data growth

Performance Optimization

Enable caching for frequently accessed data:

Terminal window
CACHE_ENABLED=true
CACHE_TTL=3600
ENABLE_QUERY_OPTIMIZATION=true

Database Optimization

For large ride datasets:

Terminal window
DATABASE_POOL_SIZE=20
DATABASE_CONNECTION_IDLE_TIMEOUT=300
DATABASE_STATEMENT_CACHE_SIZE=128

Custom Domain Configuration

To use your own domain with Bicimon:

  1. Navigate to your app’s “Domains” section in Klutch.sh
  2. Click “Add Custom Domain”
  3. Enter your domain (e.g., rides.yourdomain.com)
  4. Configure your DNS provider with a CNAME record: 
    rides.yourdomain.com → example-app.klutch.sh
  5. Klutch.sh automatically provisions SSL certificates

Advanced Features

GPS Track Management

Upload and manage GPS tracks from your rides:

Terminal window
# Upload multiple GPX files
for file in *.gpx; do
  curl -X POST https://example-app.klutch.sh/api/rides/import \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -F "gpxFile=@$file" \
    -F "bikeId=bike-123"
done

Social Features Configuration

Configure community features:

Terminal window
ENABLE_SOCIAL_FEATURES=true
ENABLE_RIDE_SHARING=true
ENABLE_COMMENTS=true
ENABLE_LIKES=true
ENABLE_CHALLENGE_CREATION=true

Weather Integration

Connect to weather services for ride conditions:

Terminal window
ENABLE_WEATHER_INTEGRATION=true
WEATHER_API_PROVIDER=openweathermap
WEATHER_API_KEY=your-api-key
WEATHER_RETENTION_DAYS=90

Security Best Practices

Authentication and Access Control

  • Use strong, unique SESSION_SECRET and JWT_SECRET
  • Regularly rotate API tokens
  • Implement role-based access control
  • Keep sensitive data secure in environment variables
  • Never commit secrets to your repository

Network Security

  • Always use HTTPS (Klutch.sh provides this automatically)
  • Limit API rate limiting to prevent abuse
  • Monitor access logs for suspicious activity
  • Implement CORS properly for API access
  • Keep dependencies updated

Data Privacy

  • Your cycling data stays on your server
  • No automatic data sharing or analytics tracking
  • Full control over data retention policies
  • Regular backups ensure data resilience
  • Encrypt sensitive data at rest

Troubleshooting

Common Issues and Solutions

Issue: Bicimon fails to start

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

  • Missing environment variables (SESSION_SECRET, JWT_SECRET)
  • Database connection issues
  • Port 3000 conflicts
  • Insufficient memory

Issue: Rides not appearing

Solutions:

  • Verify database connection is working
  • Check that /app/data volume is properly mounted
  • Review application logs for import errors
  • Verify ride data format is correct

Issue: GPS tracks not processing

Causes and solutions:

  • Check GPX file format is valid
  • Verify file size is within limits
  • Review GPS precision settings
  • Check disk space on /app/data volume

Issue: Database connection errors

Troubleshooting:

  • Verify DATABASE_URL is correct
  • Check that PostgreSQL instance is running
  • Ensure database credentials are accurate
  • Verify network connectivity to database

Issue: Slow ride uploads

Solutions:

  • Increase instance resources
  • Optimize database indexes
  • Enable caching
  • Monitor network bandwidth

Upgrading Bicimon

To update Bicimon to a newer version:

  1. Update your Dockerfile to fetch the latest code: 
    RUN git clone https://github.com/bicimon/bicimon.git . && git pull origin main
  2. Commit and push to GitHub
  3. Klutch.sh will automatically rebuild with the latest version
  4. Database migrations run automatically if DATABASE_MIGRATE=true

Additional Resources

Conclusion

Deploying Bicimon on Klutch.sh provides you with a complete, self-hosted bicycle ride tracking and management platform that respects your privacy while supporting your cycling journey. With persistent storage for your ride history, powerful analytics, social features, and beautiful visualizations, Bicimon helps you celebrate your cycling achievements and optimize your performance. Klutch.sh’s managed infrastructure ensures your cycling data is always available, secure, and performant.

Start tracking your cycling adventures today by deploying Bicimon on Klutch.sh and join a community of cyclists committed to their personal cycling growth.