Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
tusd subfolder deploy


  • tusd is hosted on
    • proxy mode is turned on : tusd --behind-proxy
  • nginx is used as reverse proxy in front of tusd
    • enables TLS and ability to use subfolders
  • uppy.js used as client for uploading

Upload flow

When tus client uploads a file a POST request is initiated

# sample
curl '' \
   -X 'POST' \ 
   -H 'upload-metadata: relativePath bnVsbA==,name ZmlsZV9leGFtcGxlX1BOR181MDBrQi5wbmc=,type aW1hZ2UvcG5n,filetype aW1hZ2UvcG5n,filename ZmlsZV9leGFtcGxlX1BOR181MDBrQi5wbmc=' 
   # all other headers needed

POST response will have a location header which will tell the client where is the file located for other tus operations (resume, download, ...)

  • location:
< HTTP/2 201 
< server: nginx/1.20.1
< date: Thu, 24 Feb 2022 08:46:46 GMT
< content-length: 0
< location:
< access-control-allow-origin:
< access-control-expose-headers: Upload-Offset, Location, Upload-Length, Tus-Version, Tus-Resumable, Tus-Max-Size, Tus-Extension, Upload-Metadata, Upload-Defer-Length, Upload-Concat
< tus-resumable: 1.0.0
< x-content-type-options: nosniff


Ending slash in proxy_pass will remove prefix /my-subfolder/ found in location when sending request to upstream server.


We need proxy_redirect to fix location header because tusd does not know how out proxy is configured.

  • it would be great if we could set out subfolder path in tusd directly but it is not possible

We just match uri with regex and fix it so that we add the subfolder back.

  • tus client will use this location header and upload will work OK
proxy_redirect ~/files/(.*)$ $scheme://$host/my-subfolder/files/$1;

If we are behind multiple proxies and use TLS on first proxy we must force HTTPS on proxy_redirect on inner proxy

proxy_redirect ~/files/(.*)$ https://$host/my-subfolder/files/$1;


Without proxy redirect in nginx upload will fail. These are some errors whis are wisible to console.

Access to XMLHttpRequest at '' from origin '' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.
[Uppy] [10:24:32] Failed to upload my-file.svg This looks like a network error, the endpoint might be blocked by an internet provider or a firewall.


  • tus subfolder
  • tusd subdir
  • tusd cors
location /my-subfolder/ {
# Forward incoming requests to local tusd instance
proxy_redirect ~/files/(.*)$ $scheme://$host/my-subfolder/files/$1;
# Disable request and response buffering
proxy_request_buffering off;
proxy_buffering off;
proxy_http_version 1.1;
# Add X-Forwarded-* headers
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
client_max_body_size 0;
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment