nginx with Etherpad in a subdirectory

Short answer: if you add a trailing slash to your prefixed location, everything would work as expected.

map $http_upgrade $connection_upgrade {
    ''      close;
    default upgrade;
}
server {
    ...
    location /etherpad/ {
        proxy_buffering off; # recommended by etherpad nginx hosting examples
        proxy_set_header Host $host;
        # optional headers
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr; # EP logs to show the actual remote IP
        proxy_set_header X-Forwarded-Proto $scheme; # for EP to set secure cookie flag when https is used
        # recommended with keepalive connections
        proxy_http_version 1.1;
        # WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        # upstream
        proxy_pass http://127.0.0.1:9001/;
    }
}

If you want /etherpad URI to work too, add the following location if you won’t get HTTP 301 redirect from /etherpad to /etherpad/ with the above configuration:

    location = /etherpad {
        return 301 /etherpad/;
    }

For me it wasn’t necessary, but it can depend on your server environment.

To preserve query string, if any, you can use return 301 /etherpad/$is_args$args; or rewrite ^ /etherpad/ permanent instead.

Long answer (and what happened undercover).

There are many question on SO about "how can I host a webapp under an URI prefix". Here is one on my answers and here is a ServerFault thread on the similar topic.

The only right way to do it is to made your proxied app request its assets via relative URIs only (consider assets/script.js instead of /assets/script.js) or using the right URI prefix (/etherpad/assets/script.js).

Luckily, etherpad requests its assets using a relative paths (e.g. <script src="static/js/index.js"></script>) making it suitable to be hosted under any URI prefix. The problem is, when your origin URI is /etherpad, browser considers the current remote web server directory as the root one, and requests above script from server as scheme://domain/static/js/index.js. That request won’t even caught by your location /etherpad { ... } (since it isn’t starts with /etherpad). On the other hand, when your origin URI is /etherpad/, browser considers the current remote web server directory as the /etherpad/ and correctly requests above script from server as scheme://domain/etherpad/static/js/index.js.

Now let’s see what happened with the proxied request /etherpad/<path> using your original configuration. Since you are using a trailing slash after the upstream address (http://localhost + /), nginx cut the location /etherpad prefix from the request URI and prepend it with that slash (or any other URI used in a proxy_pass directive after the upstream name) resulting in //<path>. You can read A little confused about trailing slash behavior in nginx or nginx and trailing slash with proxy pass SO threads for more details. Anyway that URI won’t served by etherpad giving you Cannot GET //<path> error.

Changing location /etherpad { ... } to the location /etherpad/ { ... } you’ll made both of the aforementioned problems gone.

A few words about the etherpad wiki examples, especially this one.

Both

location /etherpad/ {
    proxy_pass http://127.0.0.1/;
    ...
}

and

location /etherpad/ {
    rewrite ^/etherpad(/.*) $1 break;
    proxy_pass http://127.0.0.1;
    ...
}

do the same string – stripping the /etherpad prefix from the request URI before passing it to the upstream. However the first one do it in a much more efficient way. It is a good practice to avoid regular expressions whenever possible. Using

location = /etherpad {
    return 301 /etherpad/;
}

is also more efficient than

rewrite ^/etherpad$ /etherpad/ permanent;

Second and third location blocks from the above wiki example completely duplicate functionality from the first one. Moreover, that example breaks WebSocket support (whoever wrote it, he can at least add that support to the location /pad/socket.io { ... } block).

And never do the thing used at this example:

location ~ ^/$ { ... }

Use exact matching location instead:

location = / { ... }

Here is one more configuration I’ve tested in order to check if I can serve etherpad static assets directly via nginx. It seems to be workable, although I didn’t tested it a lot. It uses an uncompressed js/css assets versions (which should not impact performance when you are using gzip or some other compression). It is also a good example of a configuration where you can’t avoid using rewrite directive to strip a prefix from the request URI.

    location /etherpad/static/ {
        # trying to serve assets directly via nginx
        # if the asset is not found, pass the request to the nodejs upstream
        rewrite ^/etherpad(/.*) $1 break;
        root /full/path/to/etherpad-lite/src;
        try_files $uri @etherpad;
    }
    location /etherpad/ {
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:9001/;
    }
    location @etherpad {
        proxy_redirect / /etherpad/;
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:9001;
    }

Update

As being suggested on the GitHub, URIs started with /etherpad/static/plugins/ prefix should always be passed to the nodejs upstream since there are no corresponding assets would exists under the /path/to/etherpad/src/static/ directory. Despite there is already defined fallback to the nodejs upstream (try_files $uri @etherpad), to eliminate an extra stat system call produced by the try_files directive we can modify the above configuration to this one:

    location ~ ^/etherpad/static/(?!plugins/) {
        # trying to serve assets directly via nginx
        # if the asset is not found, pass the request to the nodejs upstream
        rewrite ^/etherpad(/.*) $1 break;
        root /full/path/to/etherpad-lite/src;
        try_files $uri @etherpad;
    }
    location /etherpad/ {
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:9001/;
    }
    location @etherpad {
        proxy_redirect / /etherpad/;
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:9001;
    }

(using negative lookahead regex, better readability) or to this one:

    location /etherpad/ {
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:9001/;
    }
    location /etherpad/static/ {
        rewrite ^/etherpad(/.*) $1 break;
        root /full/path/to/etherpad-lite/src;
        try_files $uri @etherpad;
    }
    location /etherpad/static/plugins/ {
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:9001/static/plugins/;
    }
    location @etherpad {
        proxy_redirect / /etherpad/;
        proxy_buffering off;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:9001;
    }

(only prefix locations, better performance). The repetitive part

proxy_buffering off;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_http_version 1.1;

and probably other optional headers (X-Real-IP, X-Forwarded-For, X-Forwarded-Proto) setup mentioned at the very beginning of the answer, can be used as a separate file, e.g. etherpad-proxy.conf, and included into the main nginx config with the include directive.