Deploying Mafl

Introduction

Mafl is a minimalist, fast, and beautiful dashboard for organizing and accessing your self-hosted services. Built with simplicity in mind, Mafl provides a clean interface to keep track of all your applications in one place without the bloat of more complex dashboard solutions.

Written with modern web technologies, Mafl focuses on performance and ease of use. Configuration is done through a simple YAML file, and the dashboard loads instantly with a beautiful, customizable design. Whether you’re running a small homelab or managing multiple services, Mafl provides an elegant starting point.

Key highlights of Mafl:

Minimalist Design: Clean, clutter-free interface focused on usability
Fast Loading: Optimized for instant load times
YAML Configuration: Simple configuration through a single YAML file
Service Icons: Automatic icon fetching or custom icon support
Status Indicators: Optional service health checking
Theme Support: Light and dark themes with customization options
Search: Quick search across all configured services
Keyboard Navigation: Navigate services with keyboard shortcuts
Mobile Responsive: Works perfectly on all devices
Docker Native: Designed for containerized deployments
Open Source: MIT licensed with simple codebase

This guide walks through deploying Mafl on Klutch.sh using Docker, configuring your services, and customizing your dashboard.

Why Deploy Mafl on Klutch.sh

Deploying Mafl on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Mafl without complex configuration.

Persistent Storage: Attach persistent volumes for your configuration. Your dashboard setup survives restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure access to your dashboard.

GitHub Integration: Connect your configuration repository directly from GitHub for automated deployments.

Lightweight Resources: Mafl is extremely lightweight, requiring minimal CPU and memory.

Custom Domains: Assign a custom domain to your dashboard for easy access.

Always-On Availability: Your dashboard remains accessible 24/7.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Mafl configuration
Basic familiarity with Docker and containerization concepts
A list of services you want to display on your dashboard
(Optional) A custom domain for your dashboard

Understanding Mafl Architecture

Mafl uses a simple architecture:

Frontend: A lightweight, static web application serving the dashboard interface.

Configuration: YAML-based configuration defining services and appearance.

Icon Fetching: Automatic favicon retrieval for configured services.

Health Checks: Optional status monitoring for services.

Preparing Your Repository

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

Repository Structure

mafl-deploy/
├── Dockerfile
├── config.yml
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM hywax/mafl:latest

# Copy configuration
COPY config.yml /app/data/config.yml

# Set environment variables
ENV PORT=3000

# Expose web interface
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

Configuration File

Create a config.yml file with your services:

title: My Dashboard
theme: dark
checkUpdates: true

services:
  - title: Media
    items:
      - title: Jellyfin
        description: Media streaming server
        link: https://jellyfin.example.com
        icon:
          name: simple-icons:jellyfin
          color: "#00A4DC"
      - title: Plex
        description: Media library
        link: https://plex.example.com
        icon:
          name: simple-icons:plex
          color: "#E5A00D"
      - title: Navidrome
        description: Music streaming
        link: https://navidrome.example.com
        icon:
          name: simple-icons:navidrome
          color: "#0064DC"

  - title: Productivity
    items:
      - title: Nextcloud
        description: Cloud storage
        link: https://cloud.example.com
        icon:
          name: simple-icons:nextcloud
          color: "#0082C9"
      - title: Paperless-ngx
        description: Document management
        link: https://docs.example.com
        icon:
          name: mdi:file-document-multiple
          color: "#17541f"
      - title: Bookstack
        description: Documentation wiki
        link: https://wiki.example.com
        icon:
          name: simple-icons:bookstack
          color: "#0288D1"

  - title: Infrastructure
    items:
      - title: Portainer
        description: Container management
        link: https://portainer.example.com
        icon:
          name: simple-icons:portainer
          color: "#13BEF9"
      - title: Grafana
        description: Monitoring dashboards
        link: https://grafana.example.com
        icon:
          name: simple-icons:grafana
          color: "#F46800"
      - title: Uptime Kuma
        description: Status monitoring
        link: https://status.example.com
        icon:
          name: simple-icons:uptimekuma
          color: "#5CDD8B"

Creating the .dockerignore File

Create a .dockerignore file:

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

Environment Variables Reference

Variable	Required	Default	Description
`PORT`	No	3000	Web server port

Deploying Mafl on Klutch.sh

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

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile config.yml .dockerignore README.md
git commit -m "Initial Mafl dashboard deployment"
git remote add origin https://github.com/yourusername/mafl-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 “mafl” or “dashboard”.

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 Mafl Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 3000

Attach Persistent Volumes

Add the following volume:

Mount Path	Recommended Size	Purpose
`/app/data`	100 MB	Configuration and cache

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 Mafl container
Provision an HTTPS certificate

Access Your Dashboard

Once deployment completes, access your Mafl dashboard at https://example-app.klutch.sh.

Configuring Services

Service Structure

Each service entry supports:

- title: Service Name
  description: Optional description
  link: https://service.example.com
  target: _blank  # Optional: _self, _blank
  icon:
    name: simple-icons:servicename
    color: "#HEXCOLOR"
    # OR
    url: https://example.com/favicon.ico
  status:
    enabled: true
    interval: 60

Service Groups

Organize services into categories:

services:
  - title: Category Name
    items:
      - title: Service 1
        ...
      - title: Service 2
        ...

Icon Options

Multiple icon sources:

# Simple Icons
icon:
  name: simple-icons:github
  color: "#181717"

# Material Design Icons
icon:
  name: mdi:server
  color: "#666666"

# Custom URL
icon:
  url: https://example.com/custom-icon.png

# Favicon (automatic)
icon:
  url: https://example.com/favicon.ico

Status Monitoring

Enable health checks:

- title: API Server
  link: https://api.example.com
  status:
    enabled: true
    interval: 60  # seconds

Customization

Themes

Configure appearance:

theme: dark  # dark, light, or system

# Custom colors
colors:
  primary: "#007bff"
  background: "#1a1a1a"

Layout Options

Adjust the layout:

layout:
  columns: 4  # Number of columns on desktop
  gap: 16     # Gap between items in pixels

Header Customization

Customize the header:

title: My Homelab
subtitle: Self-hosted services
logo: https://example.com/logo.png

Advanced Configuration

External URLs

Link to external services:

- title: GitHub
  link: https://github.com/username
  icon:
    name: simple-icons:github
  target: _blank

Nested Groups

Create sub-categories:

services:
  - title: Main Category
    items:
      - title: Sub-Group
        items:
          - title: Nested Service
            link: https://...

Keyboard Shortcuts

Mafl supports keyboard navigation:

/ or s: Focus search
1-9: Quick access to services
Enter: Open selected service
Escape: Clear search

Production Best Practices

Security Recommendations

HTTPS Only: Always access over HTTPS
Authentication: Consider reverse proxy auth for sensitive dashboards
Update Regularly: Keep Mafl updated
Link Verification: Ensure all service links use HTTPS

Performance Optimization

Icon Caching: Mafl caches icons automatically
CDN: Consider CDN for custom icons
Minimal Config: Only include services you actively use

Backup Strategy

Protect your configuration:

Git Version Control: Keep config.yml in Git
Configuration Backups: Back up /app/data
Documentation: Document your service URLs

Troubleshooting Common Issues

Icons Not Loading

Symptoms: Service icons appear broken or missing.

Solutions:

Verify icon names match Simple Icons or MDI
Check custom icon URLs are accessible
Review browser console for errors
Try alternative icon sources

Status Checks Failing

Symptoms: Status indicators show services as down.

Solutions:

Verify service URLs are accessible
Check network connectivity
Review CORS settings on monitored services
Increase check intervals

Configuration Not Loading

Symptoms: Dashboard shows empty or default config.

Solutions:

Validate YAML syntax
Check file permissions
Verify volume mount
Review container logs

Additional Resources

Conclusion

Deploying Mafl on Klutch.sh gives you a beautiful, minimalist dashboard for all your self-hosted services. The combination of Mafl’s clean design and Klutch.sh’s deployment simplicity means you can focus on organizing your services rather than configuring complex dashboard software.

With simple YAML configuration, automatic icon fetching, and optional status monitoring, Mafl provides everything you need for a homelab homepage without unnecessary complexity. Whether you’re running a few services or managing an extensive self-hosted infrastructure, Mafl on Klutch.sh offers a fast, elegant starting point for your day.