Deploying LubeLogger

Introduction

LubeLogger is an open-source, self-hosted vehicle maintenance records and fuel mileage tracker. With an unconventional name but powerful functionality, LubeLogger helps vehicle owners and fleet managers maintain comprehensive service histories, track fuel economy, and plan future maintenance with ease.

Built with .NET and backed by PostgreSQL, LubeLogger provides a clean web interface for logging oil changes, repairs, upgrades, and fuel purchases. The application supports multiple vehicles, custom service types, and detailed cost tracking, making it invaluable for personal vehicle owners and small fleet operators alike.

Key highlights of LubeLogger:

• Service Records: Log maintenance, repairs, and upgrades with full history
• Fuel Tracking: Monitor fuel economy with MPG or L/100km calculations
• Cost Analysis: Track expenses per vehicle and service type
• Multiple Vehicles: Manage unlimited vehicles in one instance
• Reminders: Set maintenance reminders by date or mileage
• Custom Fields: Add custom service types and tracking categories
• Document Storage: Attach receipts and documentation
• Data Export: Export records for backup or analysis
• Mobile Friendly: Responsive design for logging on the go
• Open Source: MIT licensed with active development

This guide walks through deploying LubeLogger on Klutch.sh using Docker, configuring your vehicle fleet, and setting up maintenance tracking.

Why Deploy LubeLogger on Klutch.sh

Deploying LubeLogger on Klutch.sh provides several advantages:

Access Anywhere: Log maintenance from any device, whether at home, the shop, or the gas station.

Persistent Storage: Attach persistent volumes for your database and documents. Service history is preserved permanently.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to your vehicle data.

GitHub Integration: Connect your configuration repository directly from GitHub for version-controlled deployments.

Custom Domains: Use a memorable domain for your vehicle tracker.

Reliable Hosting: Your maintenance records remain accessible without managing personal servers.

Data Ownership: Self-hosting ensures complete control over your vehicle history and personal data.

Prerequisites

Before deploying LubeLogger on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) A custom domain

Understanding LubeLogger Architecture

LubeLogger uses a straightforward architecture:

.NET Application: The core application is built with .NET, providing the web interface and API endpoints.

PostgreSQL Database: All vehicle data, service records, and fuel logs are stored in PostgreSQL for reliability and performance.

File Storage: Attached documents and receipts are stored on the filesystem.

Web Interface: A responsive web interface works on desktop and mobile devices.

Preparing Your Repository

To deploy LubeLogger on Klutch.sh, create a GitHub repository containing your Docker configuration.

Repository Structure

lubelogger-deploy/
├── Dockerfile
├── docker-compose.yml
├── init.sql
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/hargata/lubelogger:latest

# Set environment variables
ENV LC_Logging__LogLevel="Warning"

# Create directories for data
RUN mkdir -p /app/data /app/documents /app/images

# Expose the web interface port
EXPOSE 8080

# The base image includes the default entrypoint

Creating Docker Compose Configuration

Create docker-compose.yml for reference and local development:

version: '3.8'

services:
  lubelogger:
    image: ghcr.io/hargata/lubelogger:latest
    container_name: lubelogger
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - LC_Database__Connection=${DATABASE_URL}
      - LC_Logging__LogLevel=Warning
      - LC_Admin__Password=${ADMIN_PASSWORD}
    volumes:
      - lubelogger_data:/app/data
      - lubelogger_documents:/app/documents
      - lubelogger_images:/app/images
    depends_on:
      - db

  db:
    image: postgres:15
    container_name: lubelogger_db
    restart: unless-stopped
    environment:
      - POSTGRES_USER=lubelogger
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=lubelogger
    volumes:
      - lubelogger_pgdata:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql

volumes:
  lubelogger_data:
  lubelogger_documents:
  lubelogger_images:
  lubelogger_pgdata:

Creating the Database Init Script

Create init.sql for initial database setup:

-- Database initialization is handled by LubeLogger on first run
-- Add any custom initialization here if needed

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

LubeLogger uses environment variables prefixed with LC_:

Variable	Required	Description
LC_Database__Connection	Yes	PostgreSQL connection string
LC_Admin__Password	Recommended	Admin account password
LC_Logging__LogLevel	No	Logging verbosity (Debug, Information, Warning, Error)
LC_Email__Host	No	SMTP server for notifications
LC_Email__Port	No	SMTP port
LC_Email__Username	No	SMTP username
LC_Email__Password	No	SMTP password

Deploying LubeLogger on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Set Up Database

LubeLogger requires PostgreSQL. You can:

• Use Klutch.sh’s database services
• Deploy PostgreSQL alongside LubeLogger
• Use an external managed PostgreSQL service

Generate Passwords

Generate secure passwords:

# Admin password
openssl rand -base64 24

# Database password
openssl rand -base64 24

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile docker-compose.yml init.sql .dockerignore
git commit -m "Initial LubeLogger deployment configuration"
git remote add origin https://github.com/yourusername/lubelogger-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “lubelogger” or “vehicle-tracker”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your LubeLogger configuration.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

In the environment variables section:

Variable	Value
LC_Database__Connection	Host=your-db-host;Database=lubelogger;Username=lubelogger;Password=your_password
LC_Admin__Password	Your admin password
LC_Logging__LogLevel	Warning

Attach Persistent Volumes

Add persistent storage:

Mount Path	Recommended Size	Purpose
/app/data	1 GB	Application data and configuration
/app/documents	5 GB	Uploaded receipts and documents
/app/images	2 GB	Vehicle images

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the LubeLogger container
• Provision an HTTPS certificate

Access LubeLogger

Once deployment completes, access your LubeLogger instance at https://your-app-name.klutch.sh.

Initial Setup

First Login

When you first access LubeLogger:

1. Log in with the admin credentials you configured
2. Complete the initial setup wizard
3. Configure your preferences (units, currency, etc.)

Adding Your First Vehicle

Add a vehicle to track:

1. Click Add Vehicle
2. Enter vehicle details:
   • Year, Make, Model
   • License plate
   • VIN (optional)
   • Purchase date and mileage
   • Current odometer reading
3. Upload a vehicle photo (optional)
4. Save the vehicle

Configuring Units

Set your preferred measurement units:

1. Navigate to Settings
2. Choose distance units (miles or kilometers)
3. Choose fuel economy units (MPG or L/100km)
4. Set currency for cost tracking
5. Save preferences

Tracking Maintenance

Logging Service Records

Record maintenance and repairs:

1. Select a vehicle
2. Click Add Service Record
3. Enter details:
   • Service type (oil change, brake service, etc.)
   • Date and odometer reading
   • Cost
   • Notes and description
   • Shop/mechanic information
4. Attach receipts or documentation
5. Save the record

Service Types

Common service categories:

• Oil Change: Regular oil and filter service
• Tires: Rotation, replacement, alignment
• Brakes: Pads, rotors, fluid
• Fluids: Transmission, coolant, brake fluid
• Filters: Air, cabin, fuel
• Electrical: Battery, alternator, starter
• Engine: Tune-ups, belts, spark plugs
• Suspension: Shocks, struts, bushings
• Custom: Add your own categories

Setting Reminders

Never miss maintenance:

1. Go to Reminders
2. Create a new reminder:
   • Service type
   • Due date or mileage
   • Notification preferences
3. Receive alerts when maintenance is due

Tracking Fuel

Logging Fill-Ups

Track fuel purchases:

1. Select a vehicle
2. Click Add Fuel Record
3. Enter:
   • Date and odometer reading
   • Fuel amount (gallons or liters)
   • Price per unit
   • Total cost
   • Partial or full fill
   • Station location (optional)
4. Save the record

Fuel Economy Reports

Analyze your fuel efficiency:

• Average MPG/L: Overall fuel economy
• Cost Per Mile/Km: Fuel cost efficiency
• Trends: Track changes over time
• Comparisons: Compare between vehicles

Cost Analysis

Expense Tracking

Monitor vehicle costs:

• Total Costs: Sum of all expenses
• Cost by Category: Breakdown by service type
• Monthly/Yearly: Time-based analysis
• Per-Mile Cost: Total cost of ownership

Reports

Generate reports:

1. Navigate to Reports
2. Select report type:
   • Service history
   • Fuel economy
   • Cost summary
   • Maintenance schedule
3. Set date range
4. Export as PDF or CSV

Data Management

Importing Data

Import existing records:

1. Go to Settings → Import
2. Select import format (CSV)
3. Map columns to fields
4. Preview and confirm
5. Import records

Exporting Data

Back up your data:

1. Go to Settings → Export
2. Select data to export:
   • All vehicles
   • Specific vehicle
   • Date range
3. Choose format (CSV, JSON)
4. Download export

Document Storage

Manage attached files:

• Receipts: Proof of service
• Invoices: Detailed billing
• Warranties: Coverage documentation
• Manuals: Vehicle documentation

Production Best Practices

Security Recommendations

• Strong Passwords: Use complex admin password
• Database Security: Secure PostgreSQL access
• HTTPS Only: Always access over HTTPS
• Regular Backups: Back up database and files

Backup Strategy

Protect your vehicle records:

1. Database Backups: Regular PostgreSQL dumps
2. File Backups: Back up documents and images
3. Export Records: Periodic CSV exports
4. Offsite Storage: Store backups externally

Performance Tips

• Document Organization: Use clear naming conventions
• Regular Cleanup: Remove unnecessary old files
• Database Maintenance: Periodic vacuuming

Troubleshooting Common Issues

Cannot Log In

Symptoms: Login fails or redirects.

Solutions:

• Verify admin password is set correctly
• Check environment variable format
• Clear browser cookies
• Review application logs

Database Connection Errors

Symptoms: Application shows database errors.

Solutions:

• Verify connection string format
• Check PostgreSQL is running
• Review database credentials
• Test connection directly

Documents Not Uploading

Symptoms: File uploads fail.

Solutions:

• Check available storage space
• Verify volume permissions
• Review file size limits
• Check supported file types

Missing Records

Symptoms: Previously entered data not showing.

Solutions:

• Verify correct vehicle selected
• Check date filters
• Review database for data
• Check for database connection issues

Additional Resources

• LubeLogger GitHub Repository
• LubeLogger Documentation
• LubeLogger Official Website
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying LubeLogger on Klutch.sh gives you a comprehensive vehicle maintenance tracking system accessible from anywhere. The combination of service records, fuel tracking, and cost analysis provides complete visibility into your vehicle ownership costs.

With persistent storage for your records and documents, LubeLogger ensures your maintenance history is always available when you need it. The self-hosted approach means your vehicle data remains private and under your control.

Whether you’re managing a single car or a small fleet, LubeLogger on Klutch.sh provides the tools needed to stay on top of maintenance schedules and understand your true cost of vehicle ownership.