Skip to main content Link Menu Expand (external link) Document Search Copy Copied


Install web server & reverse proxy (NGINX)

NGINX is important to mount all components on port 80 and host the static files from Mainsail. To install NGINX you only need to execute:

sudo apt install nginx

now we create the config files with:

sudo touch /etc/nginx/sites-available/mainsail
sudo touch /etc/nginx/conf.d/upstreams.conf
sudo touch /etc/nginx/conf.d/common_vars.conf

Each file can be filled with the following content:

sudo nano /etc/nginx/conf.d/upstreams.conf

# /etc/nginx/conf.d/upstreams.conf

upstream apiserver {

upstream mjpgstreamer1 {

upstream mjpgstreamer2 {

upstream mjpgstreamer3 {

upstream mjpgstreamer4 {

Save the file with CTRL+O and close the editor with CTRL+X.

sudo nano /etc/nginx/conf.d/common_vars.conf

# /etc/nginx/conf.d/common_vars.conf

map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;

Save the file with CTRL+O and close the editor with CTRL+X.

sudo nano /etc/nginx/sites-available/mainsail

# /etc/nginx/sites-available/mainsail

server {
    listen 80 default_server;

    access_log /var/log/nginx/mainsail-access.log;
    error_log /var/log/nginx/mainsail-error.log;

    # disable this section on smaller hardware like a pi zero
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_proxied expired no-cache no-store private auth;
    gzip_comp_level 4;
    gzip_buffers 16 8k;
    gzip_http_version 1.1;
    gzip_types text/plain text/css text/xml text/javascript application/javascript application/x-javascript application/json application/xml;

    # web_path from mainsail static files
    root /home/pi/mainsail;

    index index.html;
    server_name _;

    # disable max upload size checks
    client_max_body_size 0;

    # disable proxy request buffering
    proxy_request_buffering off;

    location / {
        try_files $uri $uri/ /index.html;

    location = /index.html {
        add_header Cache-Control "no-store, no-cache, must-revalidate";

    location /websocket {
        proxy_pass http://apiserver/websocket;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 86400;

    location ~ ^/(printer|api|access|machine|server)/ {
        proxy_pass http://apiserver$request_uri;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Scheme $scheme;
    location /webcam/ {
        proxy_pass http://mjpgstreamer1/;

    location /webcam2/ {
        proxy_pass http://mjpgstreamer2/;

    location /webcam3/ {
        proxy_pass http://mjpgstreamer3/;

    location /webcam4/ {
        proxy_pass http://mjpgstreamer4/;

Save the file with CTRL+O and close the editor with CTRL+X.

Create directory for static files and active NGINX config:

mkdir ~/mainsail
sudo rm /etc/nginx/sites-enabled/default
sudo ln -s /etc/nginx/sites-available/mainsail /etc/nginx/sites-enabled/
sudo systemctl restart nginx

Now you can check again the API if it works with the reverse proxy. Open the URL http://\<printer-ip\>/printer/info in your browser. if you see a content like this:

{"result": {"state_message": "Printer is ready", "klipper_path": "/home/pi/klipper", "config_file": "/home/pi/klipper_config/printer.cfg", "software_version": "v0.9.1-785-g1be19177", "hostname": "raspberrypi", "cpu_info": "4 core ARMv7 Processor rev 4 (v7l)", "state": "ready", "python_path": "/home/pi/klippy-env/bin/python", "log_file": "/home/pi/klipper_log/klippy.log"}}

Now we can install Mainsail.

Install httpdocs

Now you can download the current Mainsail static data

cd ~/mainsail
wget -q -O && unzip && rm

Now it should be possible to open the interface: http://<printer-ip>/.

Important macros

if you want to get the full experience with Mainsail and Klipper virtual_sdcard print, you should use these macros, or use them as templates for your own.

Macro Link

Change the hostname (optional)

to use the hostname instate of the IP, you can install the avahi-daemon:

sudo apt install avahi-daemon

and you can config your hostname:

sudo raspi-config

in 2 Network Options > N1 Hostname you can edit your hostname of your Raspberry Pi. After a reboot you can use http://\<hostname\>.local/ to open the web interface.

< previous step