Skip to content
Klutch.sh Docs

Deploying Mainsail

Introduction

Mainsail is a lightweight, responsive web interface designed specifically for Klipper 3D printer firmware. It provides a modern, intuitive dashboard for monitoring and controlling your 3D printer from any device with a web browser, whether you’re across the room or across the globe.

Built with Vue.js and designed for performance, Mainsail focuses on delivering a smooth user experience even on low-powered devices. It communicates with Klipper through the Moonraker API, giving you real-time control over every aspect of your printing workflow.

Key highlights of Mainsail:

  • Responsive Design: Fully responsive interface that works seamlessly on desktops, tablets, and smartphones
  • Real-Time Monitoring: Live temperature graphs, print progress, and webcam feeds
  • G-code Console: Execute commands directly and view real-time responses from your printer
  • File Management: Upload, organize, and manage your G-code files with ease
  • Multi-Printer Support: Manage multiple printers from a single interface
  • Macro Support: Create and execute custom macros for automated workflows
  • Theme Customization: Multiple themes including dark mode for comfortable viewing
  • Webcam Integration: Monitor your prints visually with webcam support
  • Power Management: Control power devices and LED strips connected to your printer
  • Notification System: Receive alerts about print status and events

This guide walks through deploying Mainsail on Klutch.sh using Docker, configuring it to connect to your Klipper/Moonraker setup, and optimizing the interface for remote access.

Why Deploy Mainsail on Klutch.sh

Deploying Mainsail on Klutch.sh provides several advantages for managing your 3D printer remotely:

Remote Access: Access your printer interface from anywhere without setting up VPNs or exposing your home network directly to the internet.

Simplified Deployment: Klutch.sh handles the infrastructure, letting you focus on printing rather than server administration.

HTTPS by Default: Automatic SSL certificates ensure secure communication between your browser and Mainsail, especially important when accessing your printer over the internet.

Always-On Availability: Your Mainsail interface remains accessible 24/7 without keeping your local computer running.

Custom Domains: Use a memorable custom domain for your printer dashboard.

Easy Updates: Update your Mainsail deployment by pushing changes to your repository, triggering automatic rebuilds.

Prerequisites

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

  • A Klutch.sh account
  • A GitHub account with a repository for your Mainsail configuration
  • A running Klipper/Moonraker setup on your 3D printer (typically on a Raspberry Pi)
  • Your Moonraker API accessible (you’ll need to configure network access)
  • Basic familiarity with Docker and 3D printer firmware concepts

Understanding Mainsail Architecture

Mainsail operates as a static web application that communicates with your printer through the Moonraker API:

Frontend Application: Mainsail is built with Vue.js and runs entirely in your browser. The Docker container serves these static files via Nginx.

Moonraker Communication: All printer communication happens through WebSocket and HTTP connections to Moonraker, the API server that interfaces with Klipper.

No Backend Required: Since Mainsail is a frontend-only application, the deployment is lightweight and requires minimal resources.

WebSocket Real-Time Updates: Temperature data, print progress, and other metrics are streamed in real-time over WebSocket connections.

Preparing Your Repository

To deploy Mainsail on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

mainsail-deploy/
├── Dockerfile
├── config.json
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/mainsail-crew/mainsail:latest


# Copy custom configuration if needed
COPY config.json /usr/share/nginx/html/config.json


# Expose the web interface port
EXPOSE 80

Creating the Configuration File

Create a config.json file to configure Mainsail’s default settings:

{
  "instancesDB": "browser"
}

This configuration tells Mainsail to store printer instance information in the browser’s local storage. You can add multiple printers directly through the web interface after deployment.

Creating the .dockerignore File

Create a .dockerignore file to exclude unnecessary files:

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

Deploying Mainsail on Klutch.sh

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

    Push Your Repository to GitHub

    Initialize your repository and push to GitHub:

    Terminal window
    git init
    git add Dockerfile config.json .dockerignore
    git commit -m "Initial Mainsail deployment configuration"
    git remote add origin https://github.com/yourusername/mainsail-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 “mainsail” or “3d-printer-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 Mainsail Dockerfile.

    Configure HTTP Traffic

    Mainsail serves its web interface over HTTP. In the deployment settings:

    • Select HTTP as the traffic type
    • Set the internal port to 80 (Nginx’s default port)

    Deploy Your Application

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

    • Detect your Dockerfile automatically
    • Build the container image
    • Start the Mainsail container
    • Provision an HTTPS certificate

    Access Mainsail

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

Connecting to Your Printer

After deploying Mainsail, you need to configure it to connect to your Klipper/Moonraker setup.

Adding Your Printer

  1. Open your Mainsail instance in a web browser
  2. Click the + button or navigate to the printer settings
  3. Enter your Moonraker URL (e.g., http://your-printer-ip:7125)
  4. Click Save to add the printer

Network Considerations

For Mainsail to communicate with your printer, your Moonraker instance must be accessible from the internet. Options include:

Port Forwarding: Forward port 7125 from your router to your printer’s local IP. This requires configuring Moonraker’s CORS settings.

Reverse Proxy: Set up a reverse proxy (like Nginx or Traefik) on your local network to securely expose Moonraker.

VPN: Use a VPN solution to create a secure tunnel between Klutch.sh and your home network.

Tailscale/ZeroTier: Use mesh VPN solutions for secure, easy-to-configure connections.

Configuring Moonraker CORS

If accessing Moonraker remotely, update your moonraker.conf to allow CORS:

[authorization]
cors_domains:
    https://your-app-name.klutch.sh
    https://*.klutch.sh
trusted_clients:
    # Add your trusted IP ranges
    10.0.0.0/8
    127.0.0.0/8
    192.168.0.0/16

Customizing Mainsail

Theme Configuration

Mainsail supports multiple themes and customization options:

  1. Click the Settings icon in the sidebar
  2. Navigate to UI Settings
  3. Choose your preferred theme (Light, Dark, or custom)
  4. Adjust accent colors and other visual preferences

Dashboard Layout

Customize your dashboard layout:

  1. Enter edit mode by clicking the edit icon
  2. Drag and resize panels to your preference
  3. Add or remove widgets as needed
  4. Save your layout when finished

Webcam Setup

Configure webcam feeds:

  1. Go to Settings > Webcams
  2. Click Add Webcam
  3. Enter your webcam stream URL
  4. Configure rotation, flip, and FPS settings
  5. Save the configuration

Multi-Printer Management

Mainsail excels at managing multiple 3D printers:

Adding Additional Printers

  1. Click your printer name in the sidebar
  2. Select Add Printer
  3. Enter the Moonraker URL for the additional printer
  4. Give it a descriptive name
  5. Repeat for all your printers

Switching Between Printers

Use the printer dropdown in the sidebar to switch between connected printers. Each printer maintains its own settings and layout preferences.

Production Best Practices

Security Recommendations

  • Secure Moonraker Access: Never expose Moonraker directly to the internet without authentication. Use a VPN or properly configured reverse proxy with authentication.
  • Enable Moonraker Authentication: Configure Moonraker’s authorization settings to require API keys for remote access.
  • Use HTTPS Everywhere: Ensure all connections, including to Moonraker, use encrypted transport when possible.
  • Firewall Configuration: Limit access to Moonraker’s port to known IP addresses.

Performance Optimization

  • Webcam Resolution: Lower webcam resolution reduces bandwidth and improves responsiveness over slow connections.
  • Update Intervals: Adjust temperature update intervals if experiencing lag.
  • Browser Cache: Mainsail uses browser caching effectively; don’t clear it unnecessarily.

Backup Strategy

  • Browser Settings: Mainsail stores settings in browser local storage. Export your configuration regularly.
  • Moonraker Database: Back up your Moonraker configuration and database on your local printer setup.

Troubleshooting Common Issues

Cannot Connect to Printer

Symptoms: Mainsail shows “Moonraker not connected” or connection errors.

Solutions:

  • Verify Moonraker is running on your printer
  • Check that your printer’s IP is accessible from the internet
  • Confirm CORS is properly configured in moonraker.conf
  • Verify firewall rules allow incoming connections
  • Check WebSocket connections aren’t being blocked

Webcam Not Loading

Symptoms: Webcam panel shows blank or error.

Solutions:

  • Verify the webcam stream URL is accessible
  • Check if the stream requires authentication
  • Ensure CORS headers are set for the webcam stream
  • Try different stream types (MJPEG, WebRTC, HLS)

Slow or Laggy Interface

Symptoms: Dashboard updates slowly or feels unresponsive.

Solutions:

  • Reduce webcam resolution and frame rate
  • Check network latency between Klutch.sh and your printer
  • Disable unused dashboard panels
  • Close unused browser tabs

Symptoms: G-code file uploads fail or timeout.

Solutions:

  • Check Moonraker’s file upload size limits
  • Verify storage space on your printer
  • Ensure network connection is stable
  • Try smaller files to isolate the issue

Additional Resources

Conclusion

Deploying Mainsail on Klutch.sh provides a secure, always-accessible interface for monitoring and controlling your Klipper-powered 3D printer. The combination of Mainsail’s responsive design and Klutch.sh’s reliable hosting means you can check on your prints from anywhere without complex network configuration.

Whether you’re running a single printer or managing a fleet of machines, Mainsail’s intuitive interface and multi-printer support make it the ideal dashboard for your 3D printing workflow. With proper security configuration for your Moonraker API, you can enjoy remote printer management with confidence.