Reverse proxy

Table of Contents

General
Setting External URL
Server Configuration Examples
1. NGinx
NGinX + Docker (Linuxserver Letsencrypt)
Troubleshooting

The use of a reverse proxy for Stash is possible.

General

Generally, the following headers will need to be set (check your proxy’s documentation for how to configure) .

Host (http host)
X-Real-IP
X-Forwarded-For
X-Forwarded-Proto

See issue 134 for more information.

Setting External URL

You can set the base URL that will be served by Stash by adding an external_host: setting in your Stash config.yml and assigning it the full publicly accessible url

external_host: http://example.domain.com

Server Configuration Examples

NGinx

location / {
    proxy_pass http://127.0.0.1:9999;
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

NGinX + Docker (Linuxserver Letsencrypt)

If you are using the linuxserver letencrypt docker you can use create a stash.subdomain.conf file in your proxy-confs folder and use this as the config:

# make sure that your dns has a cname set for stash

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name stash.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    # enable for ldap auth, fill in ldap details in ldap.conf
    #include /config/nginx/ldap.conf;

    location / {
        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable the next two lines for ldap auth
        #auth_request /auth;
        #error_page 401 =200 /login;

        include /config/nginx/proxy.conf;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        resolver 127.0.0.11 valid=30s;
        set $upstream_app stash;
        set $upstream_port 9999;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
        proxy_set_header Host $http_host;
    }

}

Nginx with external_host

Another example for nginx:

In this case we are using stash.home as our domain and 192.168.0.1 is stash’s ip so edit acccordingly.

The external_host configuration option should also be set, in this case external_host: http://stash.home. Refer to external_host for more details

server {
    listen 80;
    listen [::]:80;

    server_name stash.home;
        client_max_body_size 0;
        location / {
           proxy_pass http://192.168.0.1:9999/;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "Upgrade";
           proxy_set_header Host $http_host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $remote_addr;
           proxy_set_header X-Forwarded-Port $server_port;
           proxy_set_header X-Forwarded-Proto $scheme;
    }

}

Apache

ProxyPass "/stash" "http://127.0.0.1:9999"
ProxyPassReverse "/stash" "http://127.0.0.1:9999"
RequestHeader setIfEmpty X-Forwarded-Prefix "/stash"
ProxyPreserveHost on

# for name resolution
ServerAdmin admin@example.com
ServerName example.com
ServerAlias stash.example.com

# to enable websockets
RewriteEngine on
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteRule ^/?stash/(.*) "ws://127.0.0.1:9999/$1" [P,L]

# to add SSL
SSLEngine on
SSLCertificateFile /path/to/cert.pem
SSLCertificateKeyFile /path/to/cert.key

Prerequisites

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_balancer
sudo a2enmod lbmethod_byrequests

sudo a2enmod rewrite
sudo a2enmod headers

# for SSL
sudo a2enmod ssl

Caddy

example.domain.com

reverse_proxy 127.0.0.1:9999 {
	header_up X-Forwarded-Host {host}
	header_up Host {upstream_hostport}
	header_up X-Real-IP {remote_host}
	header_up X-Forwarded-For {remote_host}
	header_up X-Forwarded-Port {server_port}
	header_up X-Forwarded-Proto {scheme}
}
}

Troubleshooting

504 Errors

In some cases with big database files you might encounter 504 errors during stash db migration due to timeout. Adjusting the proxy_read_timeout value ( proxy.conf file in Letencrypt/Swag docker container)

422 Errors

In order for the websocket to work, you may need to also add these lines to your server block (proxy.conf file in the Letencrypt Unraid docker container for instance) as mentioned here should fix the issue.

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";