Install and upgrade

On this page:

  1. Requirement
  2. Installation
  3. Once you are up and running
  4. Upgrade
  5. Alternative installation methods
  6. Optional: Using a reverse proxy


The official installation guide requires a Linux server with the following tools installed:

Hardware requirement is minimal: 64MB of RAM and 1 core will give you plenty of confort. If you’re expecting heavier load, we have some numbers here


The installation can be done in 3 bash commands:

~/$ mkdir filestash && cd filestash
~/filestash$ curl -O
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 322 100 322 0 0 98 0 0:00:03 0:00:03 --:--:-- 98
~/filestash$ docker-compose up -d
Creating filestash_app ...
Creating filestash_app ... done

Note: Official Docker images are made available on DockerHub.

Once the installation has complete, open up a browser and navigate to: http://your_ip:8334, you will be greet with the configurator:

setup screenshot Enter the admin password you want to use to protect the admin console that’s available under /admin.

Last step is to let Filestash configure itself depending on what you are trying to achieve: stage 2 of the setup- screenshot

At this stage, selecting Yes will expose your instance to the internet from one of our subdomain (eg without requiring any further setup from your end (see here if you worry about the automatic configuration).

How is it working? Filestash establish a bidirectional tunnel from your instance to one of our public server. Incoming requests through our domain will first hit our server to then be directed within the tunnel.

Why would I care? The motivation behind this feature is security since we discovered (big thank you to the people would have opt in the telemetry) many instances weren’t being secured properly: lack of SSL certificates, missconfiguration of reverse proxy, …

poodle ssl vulnerability

Pro and Cons: This approach isn’t perfect, it adds on latency and won’t give control of the proxy server. However, it has benefits such as:

  • it is secure by default
  • you aren’t require to be an admin of anything to make it work
  • if a security vulnerability come up, we will be able to block potential exploit

Your domain name: If you have the tunnel enable, a filestash sub domain will be automatically assigned to your instance (eg: We can change this domain to whatever you want (eg: but considering the extra cost associated with that feature (our server aren’t free) we will only do it for the people supporting the project.

Once you are up and running

  1. For a production instance, it is advised to fill the host value under configure->general with your domain name.

  2. You can enable the full text search via the admin console. This feature is disabled by default for 2 reasons:

    • associated cost when you use a vendor like S3 that charges both for the bandwith and API calls. In your settings you can change the reindex time to a higher value to minimise cost at the expense of having some stale data in your index.
    • a privacy concern as creating a searchable index will result in your instance crawling through your content and persist some data locally for the purpose of answering those search queries


Upgrade is straightforward:

~/filestash$ curl -O
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 322 100 322 0 0 98 0 0:00:03 0:00:03 --:--:-- 98
~/filestash$ docker-compose pull
Pulling app (machines/filestash:latest)...
latest: Pulling from machines/filestash
Digest: sha256:4da068a5868d736f6382618e6f8baa6cf44c1cf0f94a3ded05aa25b00a41f425
Status: Image is up to date for machines/filestash:latest
~/filestash$ docker-compose up -d
Recreating filestash_app ...
Recreating filestash_app ... done

Alternative installation methods

Warning: to date, docker is the only officially supported installation method that’s available free of charge. The reason is creating and maintaining hundreds of guides for every possible linux distribution isn’t trivial with linux packaging alone beeing a massive rabbit hole that can only be illustrated by this XKCD. If you need to have Filestash working in a production setting without docker, contact us and we’ll make it work as part of a support contract

In the meantime, community supported guides are also available:

If you want to install Filestash on your own with a more custom build approach, the reference is the Dockerfile. This recipe is just 1 example of a custom compilation that emphasis on speed, efficiency and features at the cost of installation size. You could shrink down the required space by 90% by disabling features such as image transcoding (getting rid of libvips and libraw), org-mode export (getting rid of emacs and our latex distribution) and other tools (such as pdftotext, …)

Optional: Using a reverse proxy

Using a reverse proxy isn’t mandatory but is quite usefull when you have multiple things installed on your server and can’t dedicate the port 80 and 443 to 1 application.

A sample configuration for nginx:

# change the env variable to what you want to use
openssl dhparam -out /etc/letsencrypt/live/$FILESTASH_DOMAIN/dh2048.pem -outform PEM -2 2048

cat > /etc/nginx/sites-available/filestash.conf <<EOF
server {
    listen         80;
    server_name    $FILESTASH_DOMAIN;
    return         301 https://\$server_name\$request_uri;
server {
    listen 443 ssl;
    server_name $FILESTASH_DOMAIN;
    expires \$expires;

    ssl on;
    ssl_certificate /etc/letsencrypt/live/$FILESTASH_DOMAIN/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/$FILESTASH_DOMAIN/privkey.pem;
    ssl_dhparam /etc/letsencrypt/live/$FILESTASH_DOMAIN/dh2048.pem;
    ssl_protocols TLSv1.1 TLSv1.2;
    ssl_ecdh_curve secp384r1;

    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header     Host \$host:\$server_port;
        proxy_set_header     X-Real-IP \$remote_addr;
        proxy_set_header     X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header     X-Forwarded-Proto \$scheme;
        proxy_set_header     Origin '';

        add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

        proxy_pass ;
        proxy_read_timeout   86400;

ln -s /etc/nginx/sites-available/filestash.conf /etc/nginx/sites-enabled/filestash.conf
nginx -t && service nginx restart

Note: Resist the temptation of using gzip and other caching mechanism at the reverse proxy level, you would waste valuable CPU cycles adding latency and increasing the bandwith usage, creating issues with cache invalidation. Filestash is already doing its best at compile time optimising at a level no reverse proxy could ever do with a few lines of configuration and no deep knowledge of the underlying service.

Want to contribute to this page? Edit this page!