Skip to content
Klutch.sh Docs

Deploying Eneo

Introduction

Eneo is an open-source energy management and monitoring platform designed to help organizations track, analyze, and optimize their energy consumption. With real-time data visualization, comprehensive reporting capabilities, and integration with various energy meters and sensors, Eneo enables businesses to make data-driven decisions about their energy usage, reduce costs, and minimize their environmental impact.

Deploying Eneo on Klutch.sh provides you with a scalable, secure, and reliable infrastructure for managing your energy data. This comprehensive guide walks you through deploying Eneo using a Dockerfile, configuring persistent storage for your energy data, setting up proper monitoring, and implementing production-ready best practices.

Whether you’re setting up energy monitoring for a single facility or managing a multi-site deployment, this guide provides detailed steps to get your Eneo instance running smoothly on Klutch.sh.

Prerequisites

Before you begin deploying Eneo on Klutch.sh, ensure you have the following:

  • A Klutch.sh account with access to the dashboard
  • A GitHub account and repository for your Eneo deployment
  • Basic familiarity with Docker and containerization concepts
  • Understanding of environment variables and configuration management
  • (Optional but recommended) A database instance for production deployments (PostgreSQL or MySQL)

What You’ll Learn

This guide covers:

  • Setting up your Eneo project repository
  • Creating an optimized Dockerfile for Eneo
  • Configuring persistent storage for energy data and logs
  • Deploying Eneo to Klutch.sh using the dashboard
  • Setting up environment variables and secrets
  • Configuring database connections
  • Production best practices and security considerations
  • Troubleshooting common deployment issues

Getting Started: Project Structure

A well-organized Eneo deployment repository should have the following structure:

eneo-deployment/
├── Dockerfile
├── .dockerignore
├── config/
│   └── eneo.conf (optional custom configuration)
├── scripts/
│   └── entrypoint.sh (optional startup script)
└── README.md

This structure keeps your deployment organized and makes it easy to maintain and update your Eneo instance.

Installation: Creating Your Eneo Dockerfile

Klutch.sh automatically detects a Dockerfile in your repository’s root directory and uses it to build your application. Below is a comprehensive Dockerfile for deploying Eneo with optimal performance and security.

Production-Ready Dockerfile

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

# Use a specific Node.js LTS version for stability
FROM node:18-alpine AS base


# Install system dependencies required by Eneo
RUN apk add --no-cache \
    python3 \
    make \
    g++ \
    postgresql-client \
    curl


# Set working directory
WORKDIR /app


# Create a non-root user for security
RUN addgroup -g 1001 -S eneo && \
    adduser -S eneo -u 1001


# Install Eneo - Pin to specific version for production stability
# Replace 'latest' with a specific version like eneo@1.2.3 for reproducible builds
RUN npm install -g eneo@latest


# Copy custom configuration if you have any
# COPY config/ /app/config/


# Set proper permissions
RUN chown -R eneo:eneo /app


# Switch to non-root user
USER eneo


# Expose the application port
EXPOSE 8080


# Health check to ensure the application is running
HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1


# Start Eneo
CMD ["eneo", "start", "--port", "8080", "--host", "0.0.0.0"]

Dockerfile for Development/Testing

If you’re setting up a development or testing environment, you can use a simpler Dockerfile:

FROM node:18-alpine


WORKDIR /app


# Install Eneo - Even for development, consider pinning a version
# to avoid unexpected changes. Use @latest for experimenting only.
RUN npm install -g eneo@latest


# Expose the default port
EXPOSE 8080


# Start Eneo in development mode
CMD ["eneo", "start", "--port", "8080", "--host", "0.0.0.0", "--dev"]

Note: For production deployments, always pin to a specific version (e.g., eneo@1.2.3) instead of using @latest to ensure reproducible builds and avoid unexpected breaking changes.

Understanding the Dockerfile Components

  • Base Image: Uses Alpine Linux for a smaller image size and reduced attack surface
  • System Dependencies: Installs required tools for building native modules and database connectivity
  • Non-Root User: Creates a dedicated user for enhanced security
  • Working Directory: Sets /app as the application directory
  • Port Configuration: Exposes port 8080 for HTTP traffic
  • Health Check: Enables automatic health monitoring
  • Command: Starts Eneo bound to all network interfaces for proper container networking

Important: Version Pinning for Production

For production deployments, always pin to specific versions instead of using @latest:

# Good: Specific version
RUN npm install -g eneo@1.2.3


# Avoid in production: Latest version
RUN npm install -g eneo@latest

This ensures:

  • Reproducible builds: Same code produces same results
  • Stability: Avoid unexpected breaking changes
  • Controlled updates: Update versions deliberately after testing
  • Debugging: Easier to identify version-specific issues

Deploying Eneo to Klutch.sh

Follow these detailed steps to deploy your Eneo application to Klutch.sh:

    1. Prepare Your Repository

      1. Create a new GitHub repository or use an existing one
      2. Add your Dockerfile to the repository root
      3. (Optional) Add any custom configuration files or scripts
      4. Commit and push your changes to GitHub:
      Terminal window
      git init
      git add .
      git commit -m "Initial Eneo deployment setup"
      git branch -M main
      git remote add origin https://github.com/yourusername/eneo-deployment.git
      git push -u origin main

    2. Create a Project on Klutch.sh

      1. Log in to your Klutch.sh dashboard
      2. Click on “Create New Project” or navigate to your existing project
      3. Give your project a descriptive name (e.g., “Energy Management”)
      4. Select your preferred region for deployment

    3. Create and Configure Your App

      1. Within your project, click “Create New App”
      2. Connect your GitHub repository:
        • Select your Eneo deployment repository
        • Choose the branch you want to deploy (usually main or master)
      3. Klutch.sh will automatically detect your Dockerfile in the root directory
      4. Configure the deployment settings:
        • App Name: Choose a unique name for your Eneo instance
        • Traffic Type: Select HTTP (Eneo is a web application)
        • Internal Port: Set to 8080 (the port Eneo listens on inside the container)
        • Region: Confirm or change the deployment region
        • Compute Resources: Select appropriate CPU and memory based on your expected load
          • For small deployments: 1 CPU, 1GB RAM
          • For medium deployments: 2 CPU, 2GB RAM
          • For large deployments: 4 CPU, 4GB RAM or higher
        • Number of Instances: Start with 1, scale up as needed

    4. Configure Persistent Storage

    Eneo requires persistent storage for energy data, logs, configuration, and database files (if using SQLite):

      1. In the app configuration, navigate to the “Volumes” section
      2. Click “Add Volume” to create a new persistent volume
      3. Configure the volume:
        • Mount Path: /app/data (where Eneo stores its data)
        • Volume Size: Choose based on your data retention needs:
          • For testing: 1-5 GB
          • For small deployments: 10-20 GB
          • For production: 50 GB or more
      4. (Optional) Add additional volumes if needed:
        • Mount Path: /app/logs for application logs
        • Volume Size: 5-10 GB

    5. Configure Environment Variables

    Set up the necessary environment variables for Eneo:

      1. In the app configuration, navigate to the “Environment Variables” section
      2. Add the following variables:

      Required Variables:

      Terminal window
      # Application Configuration
      NODE_ENV=production
      ENEO_PORT=8080
      ENEO_HOST=0.0.0.0
      

      # Data Storage Path
      ENEO_DATA_PATH=/app/data
      

      # Public URL (replace with your actual domain)
      ENEO_PUBLIC_URL=https://example-app.klutch.sh

      Database Configuration (if using external PostgreSQL):

      Terminal window
      # Database Connection
      DB_TYPE=postgresql
      DB_HOST=your-postgres-host
      DB_PORT=5432
      DB_NAME=eneo
      DB_USER=eneo_user
      DB_PASSWORD=your-secure-password  # Mark this as secret in Klutch.sh

      Optional Configuration:

      Terminal window
      # Session Secret (generate a random string)
      SESSION_SECRET=your-random-secret-string  # Mark as secret
      

      # API Keys (if integrating with external services)
      ENEO_API_KEY=your-api-key  # Mark as secret
      

      # Email Configuration for Notifications
      SMTP_HOST=smtp.example.com
      SMTP_PORT=587
      SMTP_USER=noreply@example.com
      SMTP_PASSWORD=your-smtp-password  # Mark as secret
      SMTP_FROM=noreply@example.com
      

      # Timezone Configuration
      TZ=America/New_York
      

      # Log Level
      LOG_LEVEL=info
      1. Mark sensitive variables (passwords, API keys, secrets) as “Secret” to prevent them from being displayed in logs

    6. Deploy Your Application

      1. Review all your configuration settings
      2. Click “Create” or “Deploy” to start the deployment process
      3. Klutch.sh will:
        • Clone your repository
        • Build the Docker image using your Dockerfile
        • Create the container with your specified configuration
        • Mount the persistent volumes
        • Inject the environment variables
        • Start your Eneo application
      4. Monitor the build and deployment logs in the dashboard
      5. Wait for the deployment to complete (typically 2-5 minutes)

    7. Access Your Eneo Instance

      1. Once deployment is complete, your app will be available at https://example-app.klutch.sh
      2. Navigate to your application URL in a web browser
      3. Complete the initial Eneo setup:
        • Create your admin account
        • Configure your organization settings
        • Set up your first energy monitoring connection
      4. Test that data is being persisted by adding some sample data and restarting the app

Persistent Storage Configuration

Eneo requires persistent storage to maintain your energy data, configuration, and logs across deployments and restarts. Here’s how to properly configure storage:

Understanding Eneo’s Storage Requirements

Eneo stores several types of data:

  • Energy measurements: Time-series data from your meters and sensors
  • Historical data: Long-term energy consumption records
  • Configuration files: System settings and user preferences
  • User data: Accounts, permissions, and customizations
  • Logs: Application and access logs for troubleshooting
  • Database files: If using SQLite (for smaller deployments)

In Klutch.sh, when adding a persistent volume, you only need to specify:

  1. Mount Path: The directory inside the container where data is stored
  2. Size: The amount of storage space to allocate

Primary Data Volume:

  • Mount Path: /app/data
  • Recommended Size:
    • Testing: 5 GB
    • Small deployment (1-10 meters): 20 GB
    • Medium deployment (10-100 meters): 100 GB
    • Large deployment (100+ meters): 500 GB or more

Logs Volume (Optional but Recommended):

  • Mount Path: /app/logs
  • Recommended Size: 10 GB

Storage Sizing Guidelines

Calculate your storage needs based on:

  • Number of energy meters/sensors
  • Data collection frequency
  • Data retention period
  • Expected growth rate

Example Calculation:

  • 10 meters × 1 reading/minute × 8 bytes × 60 minutes × 24 hours × 365 days ≈ 42 GB/year
  • Add 50% buffer for logs, metadata, and growth = ~63 GB/year

Database Storage Considerations

SQLite (Built-in):

  • Suitable for small to medium deployments
  • Data stored in /app/data/eneo.db
  • Ensure volume has sufficient space for database growth
  • Regular backups are essential

External Database (PostgreSQL/MySQL):

  • Recommended for production and large deployments
  • Better performance and reliability
  • Data stored outside the container
  • Configure using environment variables as shown above

Advanced Configuration

Using Custom Configuration Files

If you need to customize Eneo beyond environment variables, you can add configuration files to your repository:

  1. Create a config directory in your repository
  2. Add your eneo.conf or similar configuration files
  3. Update your Dockerfile to copy these files:
# Add this line to your Dockerfile
COPY config/eneo.conf /app/config/eneo.conf
  1. Update your CMD to use the custom configuration:
CMD ["eneo", "start", "--config", "/app/config/eneo.conf"]

Custom Startup Script

For more complex initialization, create an entrypoint.sh script:

#!/bin/sh
set -e


# Wait for database to be ready
if [ -n "$DB_HOST" ]; then
  echo "Waiting for database to be ready..."
  until pg_isready -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER"; do
    echo "Database is unavailable - sleeping"
    sleep 2
  done
  echo "Database is ready!"
fi


# Run database migrations
eneo migrate


# Start Eneo
exec eneo start --port 8080 --host 0.0.0.0

Update your Dockerfile:

COPY scripts/entrypoint.sh /app/entrypoint.sh
RUN chmod +x /app/entrypoint.sh
CMD ["/app/entrypoint.sh"]

Customizing Nixpacks Build

If you need to customize the build process (though Dockerfile is recommended), you can use Nixpacks environment variables:

  • NIXPACKS_BUILD_CMD: Override the build command
  • NIXPACKS_START_CMD: Override the start command
  • NIXPACKS_INSTALL_CMD: Override the install command

Traffic Configuration

Klutch.sh allows you to select the type of traffic your application handles:

  • When to use: Eneo is a web application that serves HTTP/HTTPS traffic
  • Configuration: Select “HTTP” when creating your app
  • Benefits:
    • Automatic HTTPS with TLS certificates
    • Built-in load balancing
    • Web-friendly routing
    • Compatible with Eneo’s web interface

TCP Traffic

  • When to use: For applications that require raw TCP connections (databases, custom protocols)
  • Not applicable for Eneo: Eneo uses HTTP, so select HTTP traffic
  • Port: If TCP is used, traffic is exposed on port 8000

For Eneo deployment, always select HTTP as the traffic type.

Production Best Practices

Security

    1. Use Strong Secrets:

      • Generate strong, random passwords for database connections
      • Use a cryptographically secure session secret
      • Rotate credentials regularly

    2. Implement Authentication:

      • Enable Eneo’s built-in authentication
      • Consider integrating with SSO or LDAP for enterprise deployments
      • Enforce strong password policies

    3. Network Security:

      • Use private networks for database connections when possible
      • Restrict access to administrative interfaces
      • Enable rate limiting to prevent abuse

    4. Keep Software Updated:

      • Regularly update your Eneo version
      • Monitor security advisories
      • Test updates in a staging environment first

Performance Optimization

    1. Resource Allocation:

      • Monitor CPU and memory usage
      • Scale vertically (larger instances) or horizontally (more instances) as needed
      • Set appropriate resource limits in your deployment

    2. Database Optimization:

      • Use PostgreSQL for production deployments
      • Configure appropriate connection pooling
      • Implement database query optimization
      • Set up regular maintenance tasks (VACUUM, ANALYZE)

    3. Caching:

      • Enable Eneo’s built-in caching mechanisms
      • Consider adding Redis for session storage
      • Implement CDN for static assets if needed

    4. Monitoring:

      • Set up application performance monitoring
      • Track key metrics (response time, error rates, resource usage)
      • Configure alerts for critical issues

Backup Strategy

    1. Volume Backups:

      • Create regular backups of your persistent volumes
      • Test restoration procedures periodically
      • Store backups in a separate location

    2. Database Backups:

      • If using an external database, configure automated backups
      • Maintain multiple backup versions
      • Document recovery procedures

    3. Configuration Backups:

      • Keep your Dockerfile and configuration in version control
      • Document environment variables (without exposing secrets)
      • Maintain deployment documentation

Scaling Considerations

    1. Vertical Scaling:

      • Increase CPU and memory allocation as load grows
      • Monitor resource usage to determine when to scale
      • Plan for peak usage periods

    2. Horizontal Scaling:

      • Deploy multiple instances behind a load balancer
      • Ensure session persistence across instances
      • Use external database and cache (not SQLite)

    3. Database Scaling:

      • Use read replicas for read-heavy workloads
      • Implement connection pooling
      • Consider database partitioning for very large datasets

Troubleshooting

Common Issues and Solutions

Application Won’t Start

    1. Check the deployment logs in Klutch.sh dashboard
    2. Verify all required environment variables are set
    3. Ensure the internal port (8080) matches your configuration
    4. Check that persistent volumes are properly mounted

Database Connection Errors

    1. Verify database credentials in environment variables
    2. Check network connectivity between app and database
    3. Ensure database server is running and accessible
    4. Verify database user has appropriate permissions

Data Not Persisting

    1. Confirm persistent volume is attached to the correct mount path
    2. Check volume size hasn’t been exceeded
    3. Verify file permissions (should be owned by the eneo user)
    4. Check application logs for write errors

Performance Issues

    1. Monitor resource usage (CPU, memory, disk I/O)
    2. Check database query performance
    3. Review application logs for errors or warnings
    4. Consider scaling up resources or optimizing queries

Can’t Access the Application

    1. Verify the app is running in Klutch.sh dashboard
    2. Check that HTTP traffic type is selected
    3. Ensure no firewall rules are blocking access
    4. Verify the application URL is correct

Monitoring and Maintenance

Health Checks

Your Dockerfile includes a health check that automatically monitors your application:

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

This ensures:

  • The application is responding to requests
  • Klutch.sh can automatically restart if the app becomes unhealthy
  • Load balancers route traffic only to healthy instances

Logging

Configure comprehensive logging for troubleshooting:

    1. Set appropriate log levels in environment variables
    2. Monitor logs through the Klutch.sh dashboard
    3. Consider shipping logs to an external service for long-term retention
    4. Set up log rotation to prevent disk space issues

Regular Maintenance Tasks

    1. Weekly:

      • Review application logs for errors
      • Check resource usage trends
      • Verify backups completed successfully

    2. Monthly:

      • Update Eneo to the latest version
      • Review and optimize database performance
      • Analyze storage usage and plan for growth

    3. Quarterly:

      • Review and update security configurations
      • Test disaster recovery procedures
      • Audit user accounts and permissions

Sample Code and Configuration

Complete Dockerfile Example

Here’s a production-ready Dockerfile with all recommended configurations:

# Multi-stage build for optimized image size
FROM node:18-alpine AS builder


# Install build dependencies
RUN apk add --no-cache python3 make g++


WORKDIR /build


# Install Eneo - Pin to a specific version for production
# Example: eneo@1.2.3
RUN npm install -g eneo@latest


# Final production image
FROM node:18-alpine


# Install runtime dependencies
RUN apk add --no-cache \
    curl \
    postgresql-client \
    tzdata


# Copy Eneo from builder
COPY --from=builder /usr/local/lib/node_modules/eneo /usr/local/lib/node_modules/eneo
COPY --from=builder /usr/local/bin/eneo /usr/local/bin/eneo


WORKDIR /app


# Create non-root user
RUN addgroup -g 1001 -S eneo && \
    adduser -S eneo -u 1001 && \
    mkdir -p /app/data /app/logs && \
    chown -R eneo:eneo /app


USER eneo


EXPOSE 8080


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


CMD ["eneo", "start", "--port", "8080", "--host", "0.0.0.0"]

Example .dockerignore

Create a .dockerignore file to optimize your builds:

.git
.gitignore
README.md
node_modules
npm-debug.log
.env
.env.local
*.md
.DS_Store
dist
build

Example Environment Configuration

Template for your environment variables:

Terminal window
# Application
NODE_ENV=production
ENEO_PORT=8080
ENEO_HOST=0.0.0.0
ENEO_PUBLIC_URL=https://example-app.klutch.sh


# Storage
ENEO_DATA_PATH=/app/data
ENEO_LOG_PATH=/app/logs


# Database (PostgreSQL)
DB_TYPE=postgresql
DB_HOST=your-db-host.klutch.sh
DB_PORT=5432
DB_NAME=eneo_production
DB_USER=eneo_user
DB_PASSWORD=<your-secure-password>
DB_SSL=true


# Session
SESSION_SECRET=<generate-random-64-char-string>


# Email (optional)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=<your-sendgrid-api-key>
SMTP_FROM=noreply@yourdomain.com


# Monitoring (optional)
LOG_LEVEL=info
ENABLE_METRICS=true


# Timezone
TZ=UTC

Resources

Conclusion

Deploying Eneo on Klutch.sh provides you with a robust, scalable platform for energy management and monitoring. By following this guide, you’ve learned how to:

  • Create an optimized Dockerfile for Eneo
  • Configure persistent storage for your energy data
  • Deploy to Klutch.sh using the dashboard
  • Set up production-ready configurations
  • Implement security best practices
  • Monitor and maintain your deployment

With your Eneo instance now running on Klutch.sh, you can focus on what matters most: monitoring and optimizing your energy consumption. The platform handles the infrastructure complexity, automatic scaling, and reliability, allowing you to concentrate on deriving insights from your energy data.

For questions or issues, refer to the resources section above or reach out to Klutch.sh support through the dashboard. Happy energy monitoring!