Skip to content
Klutch.sh Docs

Deploying DietPi

DietPi is an extremely lightweight Debian-based Linux distribution that’s been optimized from the ground up for minimal resource consumption. While most operating systems prioritize features and convenience, DietPi takes a different approach—it strips away everything unnecessary and focuses exclusively on efficiency. The result is a system that can run comfortably on devices with as little as 1GB of RAM and 2GB of storage, making it ideal for single-board computers, old hardware, or resource-constrained cloud environments. But don’t let the small footprint fool you—DietPi includes over 200 optimized software packages that can be installed on-demand through its dietpi-software system.

What makes DietPi special is its philosophy of “install only what you need.” Unlike bloated distributions that come pre-loaded with software you’ll never use, DietPi starts with a minimal base system and lets you add components as needed. Want a web server? Install it. Need a database? Add it. Looking to run a media server or home automation platform? DietPi has optimized installations for Plex, Home Assistant, Pi-hole, and dozens more. Each software package has been tuned for performance and minimal resource usage, with configurations that prioritize efficiency without sacrificing functionality. The included dietpi-tools provide everything from network configuration to backup management, all accessible through simple command-line interfaces.

Why Deploy DietPi on Klutch.sh?

Deploying DietPi on Klutch.sh offers several compelling advantages:

  • Minimal Resource Usage: DietPi’s lightweight nature means lower costs and better performance on modest infrastructure
  • Automated Container Setup: Klutch.sh detects your Dockerfile and handles all containerization automatically
  • Persistent Storage: Built-in volume management ensures your configurations and data survive deployments
  • Always-On Availability: Keep your DietPi services running 24/7 without maintaining local hardware
  • HTTPS Access: Secure access to web-based DietPi services with automatic SSL certificates
  • Quick Deployment: Go from code to production in minutes without manual server configuration
  • Flexible Software Stack: Install and run any of DietPi’s 200+ optimized software packages

Prerequisites

Before deploying DietPi to Klutch.sh, ensure you have:

  • A Klutch.sh account (sign up here)
  • A GitHub account with a repository for your DietPi deployment
  • Basic understanding of Docker and containerization
  • Familiarity with Linux command-line interfaces
  • Understanding of Debian-based system administration
  • Git installed on your local development machine
  • Basic knowledge of networking and service configuration

Understanding DietPi Architecture

DietPi follows a modular architecture designed for efficiency and simplicity:

Core Components

Base System

DietPi builds on Debian (currently supporting Bullseye and Bookworm), but with significant optimizations. The base system includes only essential packages—no desktop environment, no unnecessary services, no bloat. This minimal foundation typically uses less than 100MB of RAM at idle and requires under 1GB of storage. The kernel is configured for performance with unnecessary modules disabled, and system services are optimized to start quickly and consume minimal resources.

Key base features:

  • Minimal Debian foundation with optimized kernel
  • Automated first-run setup system
  • Lightweight init system (systemd optimized)
  • Efficient logging with reduced verbosity
  • Optimized APT package management
  • Automated security updates (optional)

DietPi-Software

The software installation system is DietPi’s centerpiece. Rather than maintaining separate installation scripts, DietPi-Software provides a unified interface to 200+ pre-configured, optimized applications. Each software package includes:

  • Automated dependency management
  • Optimized default configurations
  • Minimal resource usage tweaks
  • Integration with DietPi system tools
  • Automated startup configuration

Software categories include:

  • Web Servers: Nginx, Apache, Lighttpd, Caddy
  • Databases: MariaDB, PostgreSQL, Redis, InfluxDB
  • Media Servers: Plex, Jellyfin, Emby, Airsonic
  • Home Automation: Home Assistant, Node-RED, Domoticz
  • Network Services: Pi-hole, WireGuard, OpenVPN, AdGuard Home
  • Development: Docker, Git, Node.js, Python, Go
  • Monitoring: Grafana, Prometheus, Netdata, Glances
  • File Servers: Samba, NFS, ProFTPD, Nextcloud

Each installation is designed to work out of the box with sensible defaults while remaining easy to customize.

DietPi-Tools

DietPi includes a suite of management tools for common administrative tasks:

DietPi-Config: System configuration tool for adjusting performance settings, network configuration, security options, and hardware-specific tweaks. Covers everything from CPU governor settings to swap file configuration.

DietPi-Drive_Manager: Manages external drives, USB storage, and network shares. Handles formatting, mounting, and integration with DietPi services. Supports automatic mounting on boot and proper permissions management.

DietPi-Backup: Creates and restores full system backups. Supports local storage, network shares, and cloud providers. Can backup the entire system or just DietPi-specific data.

DietPi-Cleaner: Removes unnecessary files, clears caches, and optimizes disk space. Helps maintain the minimal footprint by cleaning logs, temporary files, and orphaned packages.

DietPi-Services: Manages installed services with start/stop/restart controls and automatic startup configuration. Provides a unified interface for all DietPi-installed software.

DietPi-Update: Keeps DietPi system and tools up to date. Handles both DietPi-specific updates and underlying Debian package updates. Supports automated security updates.

Configuration System

DietPi stores configuration in several locations:

  • /boot/dietpi.txt: Main configuration file with system-wide settings
  • /boot/dietpi/dietpi.txt: Alternative location on some systems
  • /var/lib/dietpi/: Runtime state and installation records
  • /etc/dietpi/: Tool-specific configurations
  • Standard Debian locations (/etc/) for installed software

The configuration system is text-based, making it easy to version control and automate deployments.

Software Installation Architecture

DietPi’s software system uses a sophisticated installation framework:

  1. Selection Phase: User selects software via dietpi-software interface or configuration file
  2. Dependency Resolution: System determines all required dependencies and optional components
  3. Download Phase: Required packages downloaded from Debian repositories or upstream sources
  4. Installation Phase: Packages installed with DietPi-specific optimizations applied
  5. Configuration Phase: Services configured with efficient defaults
  6. Integration Phase: Software integrated with DietPi tools and services
  7. Startup Configuration: Services configured to start automatically (if desired)
  8. Verification Phase: Installation verified and tested

This process ensures consistent, optimized installations every time.

Resource Optimization

DietPi achieves its efficiency through multiple optimization layers:

Memory Management

  • Minimal background services (only essentials run by default)
  • Optimized service configurations to reduce RAM usage
  • Efficient swap configuration (if needed)
  • Careful selection of lightweight alternatives (e.g., Dropbear vs OpenSSH)
  • Dynamic memory allocation based on available resources

Storage Optimization

  • Minimal base installation (< 1GB)
  • Aggressive log rotation and management
  • Removal of unnecessary documentation and locale files
  • Efficient package selection (no recommended packages by default)
  • Regular cleanup tools to maintain small footprint

CPU Optimization

  • Kernel optimizations for target hardware
  • CPU governor configuration for workload
  • Service priority optimization
  • Reduced background task frequency
  • Efficient process scheduling

Network Optimization

  • Minimal network services by default
  • Optimized network stack parameters
  • Efficient DNS configuration
  • Reduced network overhead
  • Smart connection management

Container Architecture

When running DietPi in a container, several adaptations are made:

Systemd in Container

DietPi requires systemd to manage services, which adds complexity to containerization. The container must:

  • Run systemd as PID 1
  • Mount required cgroups and tmpfs filesystems
  • Configure appropriate capabilities
  • Handle proper shutdown signals

Volume Management

Key directories should be persistent:

  • /var/lib/dietpi/: Installation state and records
  • /boot/: Configuration files (dietpi.txt)
  • /etc/: Service configurations
  • Application-specific data directories
  • Log directories (optional, for debugging)

Network Considerations

Container networking affects service access:

  • Host networking mode provides best performance
  • Bridge networking requires port mapping
  • Service discovery may need adjustment
  • DNS configuration requires special handling

Storage Requirements

DietPi is incredibly storage-efficient:

  • Base System: 400MB-1GB (minimal Debian + DietPi tools)
  • Configuration: 10-50MB (system configs and state)
  • Logs: 50-200MB (depending on verbosity settings)
  • Software: Varies by installation (each software package 10MB-1GB)
  • Application Data: Depends entirely on use case

Typical deployment scenarios:

  • Minimal Web Server: 2GB total (Nginx + PHP + minimal database)
  • Media Server: 5GB + content storage (Jellyfin or Plex)
  • Home Automation: 3-5GB (Home Assistant + database)
  • Development Environment: 5-10GB (Docker, Node.js, Python, Git)

Installation and Setup

Let’s walk through setting up DietPi for deployment on Klutch.sh.

Step 1: Create the Project Structure

First, create a new directory for your DietPi deployment:

Terminal window
mkdir dietpi-deployment
cd dietpi-deployment
git init

Step 2: Create the Dockerfile

Create a Dockerfile in the root directory. Note that running DietPi in Docker requires special configuration for systemd:

FROM debian:bookworm-slim


# Set environment variables
ENV DEBIAN_FRONTEND=noninteractive \
    DIETPI_VERSION=v9_0 \
    LANG=en_US.UTF-8 \
    LC_ALL=C


# Install systemd and required dependencies
RUN apt-get update && apt-get install -y \
    systemd \
    systemd-sysv \
    curl \
    wget \
    gnupg \
    git \
    ca-certificates \
    sudo \
    procps \
    nano \
    && rm -rf /var/lib/apt/lists/*


# Remove unnecessary systemd services
RUN cd /lib/systemd/system/sysinit.target.wants/ && \
    ls | grep -v systemd-tmpfiles-setup | xargs rm -f $1 && \
    rm -f /lib/systemd/system/multi-user.target.wants/* && \
    rm -f /etc/systemd/system/*.wants/* && \
    rm -f /lib/systemd/system/local-fs.target.wants/* && \
    rm -f /lib/systemd/system/sockets.target.wants/*udev* && \
    rm -f /lib/systemd/system/sockets.target.wants/*initctl* && \
    rm -f /lib/systemd/system/basic.target.wants/* && \
    rm -f /lib/systemd/system/anacron.timer


# Create DietPi directories
RUN mkdir -p /boot/dietpi /var/lib/dietpi /etc/dietpi /var/tmp/dietpi


# Download and install DietPi scripts
RUN cd /tmp && \
    git clone --depth=1 --branch=${DIETPI_VERSION} https://github.com/MichaIng/DietPi.git && \
    cp -R /tmp/DietPi/dietpi /boot/ && \
    cp -R /tmp/DietPi/.meta /var/lib/dietpi/ && \
    chmod +x /boot/dietpi/dietpi-* && \
    rm -rf /tmp/DietPi


# Create dietpi.txt configuration
COPY dietpi.txt /boot/dietpi.txt


# Create initialization script
COPY init-dietpi.sh /usr/local/bin/init-dietpi.sh
RUN chmod +x /usr/local/bin/init-dietpi.sh


# Create dietpi user
RUN useradd -m -s /bin/bash dietpi && \
    echo "dietpi:dietpi" | chpasswd && \
    echo "dietpi ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers


# Set up healthcheck
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD systemctl is-system-running || exit 1


# Expose common ports
EXPOSE 22 80 443 8080 3000 5000 8000


# Set working directory
WORKDIR /root


# Use systemd as init system
CMD ["/usr/local/bin/init-dietpi.sh"]

Step 3: Create DietPi Configuration

Create dietpi.txt with base configuration:

# DietPi Configuration File


# System Settings
AUTO_SETUP_LOCALE=en_US.UTF-8
AUTO_SETUP_KEYBOARD_LAYOUT=us
AUTO_SETUP_TIMEZONE=America/New_York
AUTO_SETUP_NET_ETHERNET_ENABLED=1
AUTO_SETUP_NET_WIFI_ENABLED=0
AUTO_SETUP_NET_USESTATIC=0
AUTO_SETUP_NET_HOSTNAME=dietpi


# Boot Settings
AUTO_SETUP_BOOT_WAIT_FOR_NETWORK=1
AUTO_SETUP_SWAPFILE_SIZE=1
AUTO_SETUP_SWAPFILE_LOCATION=/var/swap


# Security
AUTO_SETUP_GLOBAL_PASSWORD=dietpi
AUTO_SETUP_AUTOMATED=1
SURVEY_OPTED_IN=0


# Software Options
AUTO_SETUP_INSTALL_SOFTWARE_ID=0
AUTO_SETUP_SSH_SERVER_INDEX=-1
AUTO_SETUP_LOGGING_INDEX=-1
AUTO_SETUP_WEB_SERVER_INDEX=-1


# DietPi-Software
SOFTWARE_DISABLE_SSH_PASSWORD_LOGINS=0


# Performance
CONFIG_CPU_GOVERNOR=ondemand
CONFIG_CPU_ONDEMAND_SAMPLE_RATE=25000
CONFIG_CPU_ONDEMAND_SAMPLE_DOWNFACTOR=40
CONFIG_ENABLE_IPV6=1
CONFIG_NTP_MODE=2


# Automation
AUTO_SETUP_AUTOMATED=1
AUTO_UNMASK_LOGIND=0

Step 4: Create Initialization Script

Create init-dietpi.sh:

#!/bin/bash
set -e


echo "Starting DietPi initialization..."


# Initialize DietPi if not already done
if [ ! -f /var/lib/dietpi/.installed ]; then
    echo "First-time setup detected, initializing DietPi..."


    # Create necessary directories
    mkdir -p /var/lib/dietpi
    mkdir -p /var/tmp/dietpi
    mkdir -p /var/log


    # Initialize DietPi database
    if [ -f /boot/dietpi/dietpi-obtain_hw_model ]; then
        /boot/dietpi/dietpi-obtain_hw_model
    fi


    # Mark as installed
    touch /var/lib/dietpi/.installed


    echo "DietPi initialization complete"
fi


# Start systemd
exec /lib/systemd/systemd

Step 5: Create Software Installation Script

Create scripts/install-software.sh:

#!/bin/bash
# DietPi Software Installation Helper


echo "DietPi Software Installation Helper"
echo "===================================="
echo ""
echo "This script helps install optimized software packages"
echo ""


# Check if running as root
if [ "$EUID" -ne 0 ]; then
    echo "Please run as root or with sudo"
    exit 1
fi


# Function to install software
install_software() {
    local software_id=$1
    local software_name=$2


    echo "Installing $software_name (ID: $software_id)..."


    # Use dietpi-software for automated installation
    AUTO_SETUP_INSTALL_SOFTWARE_ID=$software_id /boot/dietpi/dietpi-software install $software_id


    if [ $? -eq 0 ]; then
        echo "✓ $software_name installed successfully"
    else
        echo "✗ Failed to install $software_name"
        return 1
    fi
}


# Display common software IDs
echo "Common Software IDs:"
echo "-------------------"
echo "Web Servers:"
echo "  83 - Nginx"
echo "  84 - Apache"
echo "  85 - Lighttpd"
echo ""
echo "Databases:"
echo "  88 - MariaDB"
echo "  89 - SQLite"
echo "  91 - PostgreSQL"
echo "  92 - Redis"
echo ""
echo "Development:"
echo "  9 - Node.js"
echo "  130 - Python 3"
echo "  162 - Docker"
echo "  17 - Git"
echo ""
echo "Media:"
echo "  41 - Plex"
echo "  42 - Jellyfin"
echo "  118 - Emby"
echo ""
echo "Example usage:"
echo "  ./install-software.sh 83  # Install Nginx"
echo ""


# If software ID provided as argument, install it
if [ -n "$1" ]; then
    install_software $1 "Software Package"
else
    echo "No software ID provided. Exiting."
fi

Step 6: Create Web Server Setup

Create scripts/setup-web-server.sh:

#!/bin/bash
# Setup Nginx web server with DietPi


echo "Setting up Nginx web server..."


# Install Nginx
/boot/dietpi/dietpi-software install 83


# Create web root
mkdir -p /var/www/html


# Create sample index page
cat > /var/www/html/index.html << 'EOF'
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>DietPi on Klutch.sh</title>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
            max-width: 800px;
            margin: 50px auto;
            padding: 20px;
            line-height: 1.6;
            color: #333;
        }
        h1 {
            color: #2c3e50;
            border-bottom: 3px solid #3498db;
            padding-bottom: 10px;
        }
        .info-box {
            background: #ecf0f1;
            padding: 20px;
            border-radius: 8px;
            margin: 20px 0;
        }
        .success {
            color: #27ae60;
            font-weight: bold;
        }
    </style>
</head>
<body>
    <h1>DietPi Web Server</h1>
    <p class="success">✓ Nginx is running successfully!</p>


    <div class="info-box">
        <h2>About This Server</h2>
        <p>This is a DietPi installation running on Klutch.sh with Nginx web server.</p>
        <p>DietPi is an extremely lightweight Debian-based Linux distribution optimized for minimal resource usage.</p>
    </div>


    <div class="info-box">
        <h2>Next Steps</h2>
        <ul>
            <li>Upload your website files to /var/www/html</li>
            <li>Configure virtual hosts in /etc/nginx/sites-available</li>
            <li>Install additional software using dietpi-software</li>
            <li>Set up SSL certificates for HTTPS</li>
        </ul>
    </div>


    <div class="info-box">
        <h2>Useful Commands</h2>
        <ul>
            <li><code>dietpi-config</code> - System configuration</li>
            <li><code>dietpi-software</code> - Software installation</li>
            <li><code>dietpi-services</code> - Service management</li>
            <li><code>systemctl status nginx</code> - Check Nginx status</li>
        </ul>
    </div>
</body>
</html>
EOF


# Set permissions
chown -R www-data:www-data /var/www/html
chmod -R 755 /var/www/html


# Restart Nginx
systemctl restart nginx


echo "Web server setup complete!"
echo "Access your server at the URL provided by Klutch.sh"

Step 7: Create Environment Configuration

Create .env.example:

Terminal window
# DietPi Configuration


# System Settings
DIETPI_TIMEZONE=America/New_York
DIETPI_HOSTNAME=dietpi
DIETPI_LOCALE=en_US.UTF-8


# Security
DIETPI_PASSWORD=dietpi
SSH_ENABLED=true
SSH_PORT=22


# Performance
CPU_GOVERNOR=ondemand
SWAPFILE_SIZE=1
ENABLE_IPV6=true


# Software Installation
# Comma-separated list of software IDs to install
AUTO_INSTALL_SOFTWARE=83,17


# Logging
LOG_LEVEL=1
LOG_CLEAN_DAYS=7


# Network
ETHERNET_ENABLED=true
WIFI_ENABLED=false
USE_STATIC_IP=false

Step 8: Create Service Management Script

Create scripts/manage-services.sh:

#!/bin/bash
# DietPi Service Management Helper


if [ "$EUID" -ne 0 ]; then
    echo "Please run as root or with sudo"
    exit 1
fi


echo "DietPi Service Management"
echo "========================"
echo ""


# Function to list services
list_services() {
    echo "Installed DietPi Services:"
    echo "-------------------------"
    systemctl list-units --type=service --state=running | grep -E "nginx|apache|mariadb|postgresql|redis|docker"
}


# Function to show service status
service_status() {
    local service=$1
    systemctl status $service
}


# Function to restart service
service_restart() {
    local service=$1
    echo "Restarting $service..."
    systemctl restart $service
    if [ $? -eq 0 ]; then
        echo "✓ $service restarted successfully"
    else
        echo "✗ Failed to restart $service"
    fi
}


# Function to enable service
service_enable() {
    local service=$1
    systemctl enable $service
    echo "✓ $service enabled for startup"
}


# Function to disable service
service_disable() {
    local service=$1
    systemctl disable $service
    echo "✓ $service disabled from startup"
}


# Main menu
case "$1" in
    list)
        list_services
        ;;
    status)
        if [ -z "$2" ]; then
            echo "Usage: $0 status <service-name>"
            exit 1
        fi
        service_status $2
        ;;
    restart)
        if [ -z "$2" ]; then
            echo "Usage: $0 restart <service-name>"
            exit 1
        fi
        service_restart $2
        ;;
    enable)
        if [ -z "$2" ]; then
            echo "Usage: $0 enable <service-name>"
            exit 1
        fi
        service_enable $2
        ;;
    disable)
        if [ -z "$2" ]; then
            echo "Usage: $0 disable <service-name>"
            exit 1
        fi
        service_disable $2
        ;;
    *)
        echo "Usage: $0 {list|status|restart|enable|disable} [service-name]"
        echo ""
        echo "Commands:"
        echo "  list              - List running services"
        echo "  status <service>  - Show service status"
        echo "  restart <service> - Restart a service"
        echo "  enable <service>  - Enable service at startup"
        echo "  disable <service> - Disable service at startup"
        exit 1
        ;;
esac

Step 9: Create Docker Ignore File

Create .dockerignore:

.git
.gitignore
*.md
README.md
.env
.DS_Store
Thumbs.db
node_modules/
*.log
.vscode
.idea
scripts/*.sh
!scripts/install-software.sh
!scripts/setup-web-server.sh
!scripts/manage-services.sh

Step 10: Create Documentation

Create README.md:

# DietPi Deployment


This repository contains a DietPi deployment configured for Klutch.sh.


## Features


- Extremely lightweight Debian-based system
- 200+ optimized software packages available
- Minimal resource usage (< 100MB RAM idle)
- Automated software installation
- Comprehensive management tools
- Systemd-based service management


## Default Credentials


- Username: `dietpi`
- Password: `dietpi`


**Change credentials immediately after deployment!**


## Quick Start


### Install Web Server


```bash
sudo /scripts/setup-web-server.sh

Install Custom Software

Terminal window
sudo /scripts/install-software.sh <SOFTWARE_ID>

Manage Services

Terminal window
sudo /scripts/manage-services.sh list
sudo /scripts/manage-services.sh restart nginx

Available Software

DietPi includes 200+ optimized software packages:

  • Web Servers: Nginx, Apache, Lighttpd, Caddy
  • Databases: MariaDB, PostgreSQL, Redis, InfluxDB
  • Development: Node.js, Python, Docker, Git
  • Media: Plex, Jellyfin, Emby, Airsonic
  • Home Automation: Home Assistant, Node-RED
  • Networking: Pi-hole, WireGuard, OpenVPN

DietPi Tools

  • dietpi-config - System configuration
  • dietpi-software - Software installation
  • dietpi-services - Service management
  • dietpi-backup - Backup and restore
  • dietpi-cleaner - System cleanup
  • dietpi-update - System updates

Configuration

Edit /boot/dietpi.txt to customize system settings.

Edit .env for environment-specific configuration.

Deployment

This application is configured to deploy on Klutch.sh with automatic Docker detection.

### Step 11: Initialize Git Repository


```bash
git add .
git commit -m "Initial DietPi setup for Klutch.sh deployment"
git branch -M master
git remote add origin https://github.com/yourusername/dietpi-deployment.git
git push -u origin master

Deploying to Klutch.sh

Now that your DietPi application is configured, let’s deploy it to Klutch.sh.

  1. Log in to Klutch.sh

    Navigate to klutch.sh/app and sign in with your GitHub account.

  2. Create a New Project

    Click “New Project” and select “Import from GitHub”. Choose the repository containing your DietPi deployment.

  3. Configure Build Settings

    Klutch.sh will automatically detect the Dockerfile in your repository. The platform will use this for building your container.

  4. Configure Traffic Settings

    Select “HTTP” as the traffic type. If you’re running web services, Klutch.sh will route HTTPS traffic to your configured web server port (typically 80 or 8080).

  5. Set Environment Variables

    In the project settings, add the following environment variables:

    • DIETPI_TIMEZONE: America/New_York (or your timezone)
    • DIETPI_HOSTNAME: dietpi
    • DIETPI_LOCALE: en_US.UTF-8
    • DIETPI_PASSWORD: Set a secure password

    Optional configuration:

    • CPU_GOVERNOR: ondemand (or performance/powersave)
    • SWAPFILE_SIZE: 1 (in GB)
    • LOG_LEVEL: 1 (0=minimal, 1=normal, 2=verbose)
    • AUTO_INSTALL_SOFTWARE: 83,17 (comma-separated software IDs)
  6. Configure Persistent Storage

    DietPi requires persistent storage for system state and data:

    • System Configuration Volume:
      • Mount path: /boot
      • Size: 1GB
    • State and Data Volume:
      • Mount path: /var/lib/dietpi
      • Size: 5GB
    • Application Data Volume:
      • Mount path: /var/www (for web content)
      • Size: 10GB
    • Logs Volume (optional):
      • Mount path: /var/log
      • Size: 2GB

    These volumes ensure your system configuration, installed software, and data persist across deployments.

  7. Deploy the Application

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

    • Clone your repository
    • Build the Docker image using your Dockerfile
    • Install DietPi base system and tools
    • Configure systemd for container operation
    • Initialize DietPi services
    • Deploy the container
    • Provision an HTTPS endpoint

    The build process typically takes 5-7 minutes due to system initialization.

  8. Access Your DietPi Instance

    Once deployment completes, you can access your DietPi instance at the provided URL (e.g., example-app.klutch.sh).

    If you’ve installed a web server, you’ll see the default page. Otherwise, you’ll need to execute commands within the container to install software.

  9. Initial Configuration

    Access the container to complete setup:

    • Change default password: passwd dietpi
    • Run system configuration: dietpi-config
    • Install software: dietpi-software
    • Update system: dietpi-update

Getting Started with DietPi

Once your DietPi instance is deployed, here’s how to use it:

First-Time Setup

Access the Container

If you need command-line access, you’ll need to execute commands through Klutch.sh’s container interface or set up SSH access.

Change Default Password

Terminal window
# Change dietpi user password
sudo passwd dietpi


# Change root password (if needed)
sudo passwd root

Update System

Terminal window
# Update DietPi and system packages
sudo dietpi-update


# Update all packages
sudo apt update && sudo apt upgrade -y

Configure System Settings

Terminal window
# Launch configuration tool
sudo dietpi-config

Navigate through menus to configure:

  • Language/Regional Options
  • Security Options
  • Performance Options
  • Advanced Options
  • Network Options

Installing Software

Using DietPi-Software

The primary method for installing optimized software:

Terminal window
# Launch software installer
sudo dietpi-software

Navigate the menu to:

  1. Browse software categories
  2. Select software to install
  3. Review selections
  4. Confirm installation

Common Software IDs

For automated installation, use software IDs:

Web Servers

Terminal window
# Install Nginx
sudo dietpi-software install 83


# Install Apache
sudo dietpi-software install 84


# Install Lighttpd
sudo dietpi-software install 85


# Install Caddy
sudo dietpi-software install 162

Databases

Terminal window
# Install MariaDB
sudo dietpi-software install 88


# Install PostgreSQL
sudo dietpi-software install 91


# Install Redis
sudo dietpi-software install 92


# Install InfluxDB
sudo dietpi-software install 75

Development Tools

Terminal window
# Install Node.js
sudo dietpi-software install 9


# Install Python 3
sudo dietpi-software install 130


# Install Docker
sudo dietpi-software install 162


# Install Git
sudo dietpi-software install 17

Media Servers

Terminal window
# Install Jellyfin
sudo dietpi-software install 42


# Install Plex
sudo dietpi-software install 41


# Install Emby
sudo dietpi-software install 118

Setting Up a Web Server

Install and Configure Nginx

Terminal window
# Install Nginx
sudo dietpi-software install 83


# Create web directory
sudo mkdir -p /var/www/html


# Set permissions
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html


# Create test page
cat << 'EOF' | sudo tee /var/www/html/index.html
<!DOCTYPE html>
<html>
<head>
    <title>DietPi Web Server</title>
</head>
<body>
    <h1>Welcome to DietPi on Klutch.sh</h1>
    <p>Your web server is running successfully!</p>
</body>
</html>
EOF


# Test configuration
sudo nginx -t


# Restart Nginx
sudo systemctl restart nginx


# Enable on startup
sudo systemctl enable nginx

Configure Virtual Hosts

Create a new site configuration:

Terminal window
# Create site config
sudo nano /etc/nginx/sites-available/myapp

Add configuration:

server {
    listen 80;
    server_name example-app.klutch.sh;
    root /var/www/html;
    index index.html index.htm;


    location / {
        try_files $uri $uri/ =404;
    }


    # Enable gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;


    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
}

Enable the site:

Terminal window
# Create symlink
sudo ln -s /etc/nginx/sites-available/myapp /etc/nginx/sites-enabled/


# Remove default site if needed
sudo rm /etc/nginx/sites-enabled/default


# Test configuration
sudo nginx -t


# Reload Nginx
sudo systemctl reload nginx

Database Setup

Install and Configure MariaDB

Terminal window
# Install MariaDB
sudo dietpi-software install 88


# Secure installation
sudo mysql_secure_installation


# Create database and user
sudo mysql -u root -p << 'EOF'
CREATE DATABASE myapp_db;
CREATE USER 'myapp_user'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON myapp_db.* TO 'myapp_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
EOF


# Enable on startup
sudo systemctl enable mariadb

Install PostgreSQL

Terminal window
# Install PostgreSQL
sudo dietpi-software install 91


# Switch to postgres user
sudo -u postgres psql << 'EOF'
CREATE DATABASE myapp_db;
CREATE USER myapp_user WITH ENCRYPTED PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE myapp_db TO myapp_user;
\q
EOF


# Enable on startup
sudo systemctl enable postgresql

Install Redis

Terminal window
# Install Redis
sudo dietpi-software install 92


# Configure Redis
sudo nano /etc/redis/redis.conf


# Set password (uncomment and modify)
# requirepass your_secure_password


# Restart Redis
sudo systemctl restart redis-server


# Enable on startup
sudo systemctl enable redis-server


# Test connection
redis-cli ping

Development Environment Setup

Node.js Application

Terminal window
# Install Node.js
sudo dietpi-software install 9


# Verify installation
node --version
npm --version


# Create application directory
mkdir -p /var/www/nodeapp
cd /var/www/nodeapp


# Initialize project
npm init -y


# Install Express
npm install express


# Create sample app
cat << 'EOF' > app.js
const express = require('express');
const app = express();
const port = 3000;


app.get('/', (req, res) => {
  res.send('Hello from DietPi on Klutch.sh!');
});


app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});
EOF


# Install PM2 for process management
sudo npm install -g pm2


# Start application
pm2 start app.js --name myapp


# Enable startup
pm2 startup
pm2 save

Python Application

Terminal window
# Install Python 3
sudo dietpi-software install 130


# Install pip packages
sudo apt install python3-pip python3-venv -y


# Create virtual environment
mkdir -p /var/www/pythonapp
cd /var/www/pythonapp
python3 -m venv venv


# Activate virtual environment
source venv/bin/activate


# Install Flask
pip install flask gunicorn


# Create sample app
cat << 'EOF' > app.py
from flask import Flask


app = Flask(__name__)


@app.route('/')
def hello():
    return 'Hello from DietPi on Klutch.sh!'


if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)
EOF


# Create systemd service
cat << 'EOF' | sudo tee /etc/systemd/system/pythonapp.service
[Unit]
Description=Python Flask Application
After=network.target


[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/pythonapp
Environment="PATH=/var/www/pythonapp/venv/bin"
ExecStart=/var/www/pythonapp/venv/bin/gunicorn --workers 3 --bind 0.0.0.0:5000 app:app


[Install]
WantedBy=multi-user.target
EOF


# Start service
sudo systemctl daemon-reload
sudo systemctl start pythonapp
sudo systemctl enable pythonapp

Service Management

Using DietPi-Services

Terminal window
# Launch service manager
sudo dietpi-services

Features:

  • Start/stop/restart services
  • Enable/disable startup
  • View service status
  • Check logs

Using systemctl Directly

Terminal window
# Check service status
sudo systemctl status nginx


# Start service
sudo systemctl start nginx


# Stop service
sudo systemctl stop nginx


# Restart service
sudo systemctl restart nginx


# Reload configuration
sudo systemctl reload nginx


# Enable on startup
sudo systemctl enable nginx


# Disable from startup
sudo systemctl disable nginx


# View logs
sudo journalctl -u nginx -f

System Maintenance

Using DietPi-Cleaner

Terminal window
# Launch cleaner
sudo dietpi-cleaner

Options:

  • Clear logs
  • Remove temporary files
  • Clean APT cache
  • Remove orphaned packages
  • Clear thumbnail cache

Manual Cleanup

Terminal window
# Clean APT cache
sudo apt clean
sudo apt autoclean


# Remove orphaned packages
sudo apt autoremove -y


# Clear old logs
sudo journalctl --vacuum-time=7d


# Clear tmp files
sudo rm -rf /tmp/*
sudo rm -rf /var/tmp/*


# Check disk usage
df -h
du -sh /var/* | sort -h

Advanced Configuration

Optimizing Performance

CPU Governor Configuration

Terminal window
# Check current governor
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor


# Set performance mode (maximum performance)
echo "performance" | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor


# Set ondemand mode (balanced)
echo "ondemand" | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor


# Set powersave mode (minimal power)
echo "powersave" | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor


# Make permanent via dietpi.txt
sudo nano /boot/dietpi.txt
# Set: CONFIG_CPU_GOVERNOR=performance

Memory Optimization

Terminal window
# Configure swap
sudo dietpi-drive_manager


# Adjust swappiness (lower = less swap usage)
echo "vm.swappiness=10" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p


# Check memory usage
free -h

Disk I/O Optimization

Terminal window
# Check current scheduler
cat /sys/block/sda/queue/scheduler


# Set deadline scheduler (good for SSDs)
echo "deadline" | sudo tee /sys/block/sda/queue/scheduler


# Enable TRIM for SSD (if applicable)
sudo systemctl enable fstrim.timer
sudo systemctl start fstrim.timer

Network Configuration

Configure Static IP

Edit /boot/dietpi.txt:

AUTO_SETUP_NET_USESTATIC=1
AUTO_SETUP_NET_STATIC_IP=192.168.1.100
AUTO_SETUP_NET_STATIC_MASK=255.255.255.0
AUTO_SETUP_NET_STATIC_GATEWAY=192.168.1.1
AUTO_SETUP_NET_STATIC_DNS=8.8.8.8 8.8.4.4

Configure DNS

Terminal window
# Edit resolv.conf
sudo nano /etc/resolv.conf


# Add DNS servers
nameserver 8.8.8.8
nameserver 8.8.4.4
nameserver 1.1.1.1

Optimize Network Stack

Terminal window
# Add to /etc/sysctl.conf
cat << 'EOF' | sudo tee -a /etc/sysctl.conf
# Network optimization
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216
net.ipv4.tcp_congestion_control = bbr
net.core.default_qdisc = fq
EOF


# Apply changes
sudo sysctl -p

Automated Backups

Configure DietPi-Backup

Terminal window
# Launch backup tool
sudo dietpi-backup

Configure:

  • Backup location (local or network)
  • Backup schedule
  • What to include/exclude
  • Retention policy

Manual Backup Script

Create /usr/local/bin/backup.sh:

#!/bin/bash
# DietPi Backup Script


BACKUP_DIR="/backups/dietpi-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"


echo "Starting backup to $BACKUP_DIR..."


# Backup configuration
echo "Backing up configuration..."
cp -r /boot/dietpi* "$BACKUP_DIR/"
cp -r /var/lib/dietpi "$BACKUP_DIR/"


# Backup web content
if [ -d /var/www ]; then
    echo "Backing up web content..."
    tar czf "$BACKUP_DIR/www.tar.gz" /var/www
fi


# Backup databases
if systemctl is-active --quiet mariadb; then
    echo "Backing up MariaDB databases..."
    sudo mysqldump --all-databases > "$BACKUP_DIR/mariadb-all.sql"
fi


if systemctl is-active --quiet postgresql; then
    echo "Backing up PostgreSQL databases..."
    sudo -u postgres pg_dumpall > "$BACKUP_DIR/postgresql-all.sql"
fi


# Backup service configurations
echo "Backing up service configurations..."
cp -r /etc/nginx "$BACKUP_DIR/" 2>/dev/null || true
cp -r /etc/apache2 "$BACKUP_DIR/" 2>/dev/null || true


echo "Backup complete: $BACKUP_DIR"


# Clean old backups (keep last 7 days)
find /backups -type d -name "dietpi-*" -mtime +7 -exec rm -rf {} \;

Make executable and schedule:

Terminal window
sudo chmod +x /usr/local/bin/backup.sh


# Add to crontab (daily at 2 AM)
(crontab -l 2>/dev/null; echo "0 2 * * * /usr/local/bin/backup.sh") | crontab -

Custom Software Installation

Installing Software Not in DietPi Repository

Terminal window
# Example: Installing custom application
cd /opt
sudo git clone https://github.com/user/custom-app.git
cd custom-app


# Install dependencies
sudo apt install -y dependency1 dependency2


# Build if needed
make
sudo make install


# Create systemd service
cat << 'EOF' | sudo tee /etc/systemd/system/custom-app.service
[Unit]
Description=Custom Application
After=network.target


[Service]
Type=simple
User=dietpi
WorkingDirectory=/opt/custom-app
ExecStart=/opt/custom-app/bin/start
Restart=always


[Install]
WantedBy=multi-user.target
EOF


# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable custom-app
sudo systemctl start custom-app

Security Hardening

Configure Firewall

Terminal window
# Install UFW
sudo apt install ufw -y


# Default policies
sudo ufw default deny incoming
sudo ufw default allow outgoing


# Allow SSH
sudo ufw allow 22/tcp


# Allow HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp


# Enable firewall
sudo ufw enable


# Check status
sudo ufw status verbose

Install Fail2Ban

Terminal window
# Install Fail2Ban
sudo apt install fail2ban -y


# Create local configuration
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local


# Configure SSH protection
sudo nano /etc/fail2ban/jail.local


# Find [sshd] section and enable:
# enabled = true
# maxretry = 3
# bantime = 3600


# Restart Fail2Ban
sudo systemctl restart fail2ban


# Check status
sudo fail2ban-client status

Automated Security Updates

Terminal window
# Install unattended-upgrades
sudo apt install unattended-upgrades -y


# Configure
sudo dpkg-reconfigure -plow unattended-upgrades


# Edit configuration
sudo nano /etc/apt/apt.conf.d/50unattended-upgrades


# Enable automatic reboot if needed
# Unattended-Upgrade::Automatic-Reboot "true";
# Unattended-Upgrade::Automatic-Reboot-Time "02:00";

Production Best Practices

Follow these recommendations for running DietPi in production:

Security

Change Default Credentials

Never use default passwords:

Terminal window
# Change dietpi password
sudo passwd dietpi


# Change root password
sudo passwd root


# Disable root login (optional)
sudo passwd -l root

SSH Security

Configure secure SSH access:

Terminal window
# Edit SSH config
sudo nano /etc/ssh/sshd_config


# Recommended settings:
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
Port 2222  # Change default port
MaxAuthTries 3
ClientAliveInterval 300
ClientAliveCountMax 2


# Restart SSH
sudo systemctl restart sshd

Regular Updates

Keep system updated:

Terminal window
# Update DietPi
sudo dietpi-update


# Update packages
sudo apt update && sudo apt upgrade -y


# Enable automatic security updates
sudo dpkg-reconfigure -plow unattended-upgrades

File Permissions

Set appropriate permissions:

Terminal window
# Web files
sudo chown -R www-data:www-data /var/www
sudo find /var/www -type d -exec chmod 755 {} \;
sudo find /var/www -type f -exec chmod 644 {} \;


# Configuration files
sudo chmod 644 /boot/dietpi.txt
sudo chmod 600 /etc/ssh/sshd_config

Performance

Resource Monitoring

Monitor system resources:

Terminal window
# Install htop
sudo apt install htop -y


# Monitor resources
htop


# Check disk usage
df -h
du -sh /var/www/* | sort -h


# Check memory
free -h


# Check load average
uptime


# Monitor network
sudo apt install nethogs -y
sudo nethogs

Optimize Services

Disable unnecessary services:

Terminal window
# List all services
systemctl list-unit-files --type=service


# Disable unnecessary services
sudo systemctl disable bluetooth
sudo systemctl disable avahi-daemon


# Stop services
sudo systemctl stop bluetooth
sudo systemctl stop avahi-daemon

Database Optimization

Optimize database performance:

MariaDB

Terminal window
# Edit configuration
sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf


# Add optimizations:
[mysqld]
innodb_buffer_pool_size = 256M
innodb_log_file_size = 64M
innodb_flush_method = O_DIRECT
max_connections = 100
query_cache_size = 32M
query_cache_limit = 2M


# Restart MariaDB
sudo systemctl restart mariadb

Reliability

Health Checks

Monitor service health:

# Create health check script
cat << 'EOF' > /usr/local/bin/healthcheck.sh
#!/bin/bash


# Check critical services
services=("nginx" "mariadb" "redis-server")


for service in "${services[@]}"; do
    if systemctl is-active --quiet "$service"; then
        echo "✓ $service is running"
    else
        echo "✗ $service is down"
        # Send alert or restart service
        systemctl restart "$service"
    fi
done


# Check disk space
usage=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')
if [ "$usage" -gt 90 ]; then
    echo "✗ Disk usage critical: ${usage}%"
fi


# Check memory
mem_usage=$(free | grep Mem | awk '{printf "%.0f", $3/$2 * 100}')
if [ "$mem_usage" -gt 90 ]; then
    echo "✗ Memory usage high: ${mem_usage}%"
fi
EOF


sudo chmod +x /usr/local/bin/healthcheck.sh


# Run every 5 minutes
(crontab -l 2>/dev/null; echo "*/5 * * * * /usr/local/bin/healthcheck.sh") | crontab -

Log Management

Manage logs effectively:

Terminal window
# Configure log rotation
sudo nano /etc/logrotate.d/dietpi


# Add configuration:
/var/log/dietpi/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
}


# Limit journal size
sudo journalctl --vacuum-size=100M
sudo journalctl --vacuum-time=7d


# Configure persistent journal limit
sudo nano /etc/systemd/journald.conf
# SystemMaxUse=100M

Automated Monitoring

Set up monitoring alerts:

# Create monitoring script
cat << 'EOF' > /usr/local/bin/monitor.sh
#!/bin/bash


# Configuration
ALERT_EMAIL="admin@example.com"
LOG_FILE="/var/log/dietpi/monitor.log"


# Check system load
load=$(uptime | awk -F'load average:' '{print $2}' | awk '{print $1}' | sed 's/,//')
threshold=2.0


if (( $(echo "$load > $threshold" | bc -l) )); then
    echo "$(date): High load detected: $load" >> "$LOG_FILE"
    # Send alert
fi


# Check service status
for service in nginx mariadb redis-server; do
    if ! systemctl is-active --quiet "$service"; then
        echo "$(date): Service $service is down" >> "$LOG_FILE"
        systemctl restart "$service"
    fi
done
EOF


sudo chmod +x /usr/local/bin/monitor.sh


# Schedule every minute
(crontab -l 2>/dev/null; echo "* * * * * /usr/local/bin/monitor.sh") | crontab -

Troubleshooting

Common Issues

Problem: Container won’t start or crashes immediately

Solutions:

  • Check systemd is running properly
  • Verify required volumes are mounted
  • Check logs: docker logs container_name
  • Ensure proper capabilities for systemd
  • Verify init script is executable

Problem: DietPi tools not found

Solutions:

  • Verify DietPi scripts installed: ls /boot/dietpi/
  • Check PATH includes /boot/dietpi
  • Re-run initialization: /usr/local/bin/init-dietpi.sh
  • Verify scripts are executable: chmod +x /boot/dietpi/dietpi-*

Problem: Software installation fails

Solutions:

  • Update package lists: sudo apt update
  • Check disk space: df -h
  • Review installation logs
  • Try manual installation: sudo dietpi-software install <ID>
  • Check internet connectivity

Service Issues

Problem: Web server not accessible

Solutions:

  • Check service status: sudo systemctl status nginx
  • Verify port binding: sudo netstat -tlnp | grep 80
  • Check firewall: sudo ufw status
  • Review error logs: sudo tail -f /var/log/nginx/error.log
  • Test configuration: sudo nginx -t

Problem: Database won’t start

Solutions:

  • Check error logs: sudo journalctl -u mariadb -n 50
  • Verify data directory permissions
  • Check disk space
  • Review configuration: /etc/mysql/mariadb.conf.d/50-server.cnf
  • Try repair: sudo mysql_upgrade --force

Problem: Services consuming too much memory

Solutions:

  • Identify culprit: top or htop
  • Restart service: sudo systemctl restart <service>
  • Optimize service configuration
  • Increase swap: Edit /boot/dietpi.txt
  • Consider resource limits

Performance Issues

Problem: System slow or unresponsive

Solutions:

  • Check CPU load: uptime
  • Check memory: free -h
  • Check disk I/O: iostat -x 1
  • Identify processes: top
  • Kill problematic processes: kill -9 <PID>
  • Reboot if necessary

Problem: Disk space filling up

Solutions:

  • Check usage: df -h
  • Find large files: du -sh /* | sort -h
  • Clean logs: sudo dietpi-cleaner
  • Clear APT cache: sudo apt clean
  • Remove old backups
  • Increase volume size if needed

Problem: High network usage

Solutions:

  • Monitor connections: sudo nethogs
  • Check listening services: sudo netstat -tlnp
  • Review firewall rules
  • Limit bandwidth per service
  • Check for unauthorized access

Configuration Issues

Problem: Changes not persisting after restart

Solutions:

  • Verify volumes mounted correctly
  • Check file permissions
  • Ensure editing correct config file location
  • Verify systemd service files saved
  • Check if config changes require service restart

Problem: Can’t install certain software

Solutions:

  • Check software availability: dietpi-software list
  • Verify dependencies installed
  • Check architecture compatibility
  • Try alternative software
  • Manual installation from source

Additional Resources

Conclusion

DietPi represents a philosophy that more doesn’t always mean better—sometimes the most powerful solution is the one that uses the least resources. By stripping away unnecessary bloat and focusing exclusively on efficiency, DietPi delivers an operating system that runs smoothly on modest hardware while still providing access to hundreds of optimized software packages. Whether you’re running a simple web server, a complex home automation setup, or a development environment, DietPi gives you the tools to do it efficiently.

Deploying DietPi on Klutch.sh combines the lightweight efficiency of DietPi with the convenience of managed container hosting. You get all the benefits of DietPi’s minimal resource usage and extensive software library without the hassle of maintaining physical hardware or configuring servers from scratch. Your services run 24/7, accessible from anywhere, with automatic HTTPS and persistent storage built in. Whether you need a web server, database, media server, or custom application stack, DietPi on Klutch.sh provides a solid, efficient foundation that won’t consume unnecessary resources or cost you unnecessary money.

Start your lightweight Linux journey with DietPi today and experience what computing can be when every byte counts.