Install and upgrade

On this page:

1. Requirements
2. Installation
3. Configuration
4. Plugins
5. Going to Prod
6. Upgrade

Requirements

All you need is a Linux server with these tools installed:

• docker
• docker-compose
• curl

Hardware requirement is minimal: 128MB of RAM and 1 core will suffice, provided you’re not doing intensive video transcoding and/or serving thousands of users simultaneously.

Installation

The official Docker image is available on Docker Hub

After installation, navigate to http://your_domain:8334 to configure your admin password:

Configuration

For a basic setup, just pick the storage backends you need, and you’re good to go:

This is the setup we use for the publicly available demo. If that’s all you need, you can jump straight to going to prod.

Passthrough Pattern

Now that we’ve covered the basics, let’s dive into the cooler stuff, connecting your storage to different authentication and authorization sources. There are plenty of valid strategies for this, but we’ll start with the simplest one, the passthrough middleware:

If you go with the same exact configuration in the screenshot above, users will see a much simpler login screen like this:

At this point, the user experience is already much better than having them type in the correct “hostname” and “port” like before. The connection is established using a mix of static values, such as the hardcoded “ftp.gnu.org” hostname from the admin configuration, and dynamic variables, which in this case are the username and password entered by the user. Another common strategy is to create automatic login links. To do this, simply change the strategy in the configuration to “direct” and set everything up statically or through URL variables. This approach is especially useful if you want to generate QR codes or deep URLs, in which case security can be preserved through URL signatures.

Facade Pattern

Another very different pattern is to create a “facade” for your storage using methods like “htpasswd”, “OIDC”, “SAML”, or “LDAP”. In practice, it looks like this:

In the setup above, only two users with their own username and password are allowed access, and the path variable is dynamically generated based on who has successfully authenticated. The user “rick” has full access to all S3 buckets, while the user “jerry” is restricted to the “earth” bucket only.

Under the hood, these mappings are done using the Go templating language, along with a few custom functions to enable more advanced use cases. For example, you can dynamically generate chroot paths based on AD groups by building queries like this: {{ if contains .memberOf “ADMIN”}}/{{ else }}/{{ .department }}/{{ endif }}.

Plugins

So far, we’ve only touched on storage plugins and authentication middleware, which are 2 of the 3 pillars of a solid bespoke solution:

Yet, we’re only beginning to tap into the potential of plugins. Filestash is more than just a ready-to-use tool; it’s built as a framework for developing file management applications. Once you take a closer look, you’ll find a core engine surrounded by plugins that define almost every aspect of the file manager.

To cite a few examples of what plugins can do, you can layer a complete authorisation framework, override frontend code to change the default set of icons, disable viewers, add buttons specific to your use case, or even build entire file viewer applications like our OnlyOffice integration which supports office documents, change how configuration is being stored and saved to something like S3 or via environment variables, disable search or go the full text search path with either the sqlite plugin or integrate with your existing Elasticsearch or Solr cluster. We’ve gone so far that if the thought of a buffer overflow makes you sweat, you can switch the default thumbnail generators written in C for another implementation made entirely in Go or disable it altogether.

You can see all the plugins installed in your build on the /about page of your Filestash instance:

The plugin based architecture runs deep in the software and allows for the kind of customisation that would be impossible with any other solution. If you have very specific needs, there’s good chance custom plugin can work for you and we can assist you every step of the way in your project

If you’re eager to explore the power of plugins, delving into the source code is your best bet. A good starting point for this exploration is this and this.

Going to Prod

SSL & Load Balancer

Most enterprises will want to bring their own SSL certificates and use an ELB (Elastic Load Balancer) to proxy requests to the service, ensuring high availability. The base image plays well with this kind of setup but if you live in a simpler world, you have a couple options:

1. setup a reverse proxy sitting as a middleman and handling the SSL termination there. In practice it means you will be using something like certbot to generate SSL certificate and have something like nginx sitting as a middle man configured with proxy_pass to “http://ip_of_the_service:8334” and ssl certificate installed like this.

2. use another plugin that make Filestash speaks HTTPS natively without reverse proxy. There’s 2 variations of such plugins, one that does SSL through letsencrypt and another where you need to insert your certificate in a particular location.

Advanced Setup

Filestash is deployed in many sensitive environments with very stringent needs. If this sounds like what you are doing, you might want to read:

1. our hardening guide

2. some examples of architecture diagram that was made for a deployment in large pharma with requirements for high availability and scalability. You can read about that in this post from the AWS Blog:

Upgrade

To update Filestash: