Install and upgrade

On this page:

  1. Requirements
  2. Installation
  3. Setup
  4. Plugins
  5. Upgrade

Requirements

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

~/$ docker -v
Docker version 19.03.8, build afacb8b7f0
~/$ docker-compose -v
docker-compose version 1.24.0, build 0aa59064
~/$ curl --version
curl 7.70.0 (x86_64-pc-linux-gnu) ...
Release-Date: 2020-04-29
Protocols: ...
Features: ...

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 images are available on docker hub.

~/$ mkdir filestash && cd filestash
~/filestash$ curl -O https://downloads.filestash.app/latest/docker-compose.yml
% 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

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

setup screenshot

Setup

You can pick and choose which storages you want your users to access:

storage backend screenshot
Example with only FTP & S3 enabled, appearing as "A FTP" and "AWS S3"

Behind the scenes, “storage plugins” power each storage option in Filestash, providing a unified web interface that encapsulates the main functionalities of Filezilla, Cloudberry, WinSCP, and Cyberduck. This setup alone meets a wide range of needs but we can unlock some more powerful capabilities via “authentication middleware”:

auth middleware screenshot using passthrough to be used as an FTP client

By enabling an “Authentication middleware” plugin like the passthrough option shown above, you spare users from knowing and entering the technical details of your storage like hostname, port, access_keys, … etc… These parameters will then be used to connect to your storage which in this case would show:

resulting frontend as an FTP client
Authenticating as "anonymous" to ftp.gnu.org

Another very common pattern is to use a plugin like the htpasswd to create a facade for your storage:

auth middleware to be used as a S3 browser

This setup grants “rick” complete access to all S3 buckets, whereas “jerry” is restricted to the “earth” bucket only. These mappings can make use of the Go templating language, enriched to enable the use of environment variables and additional functions like “.contains”, which are very handy for setting up role-based access.

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:

STORAGE
SERVER
STORAGE...
FILESTASH CORE
FILESTASH CORE
AUTHENTICATION
SERVER
AUTHENTICATION...
AUTHORIZATION
AUTHORIZATION
Storage Plugins
Storage Plugins
FTP
FTP
SFTP
SFTP
S3
S3
...
...
Auth Plugins
Auth Plugins
Middleware Plugins
Middleware Plugins
HTPASSWORD
HTPASSWORD
SSO
SSO
...
...
READ ONLY
READ ONLY
...
...
ROLE
ROLE
Text is not SVG - cannot display
Storage plugins implements the IBackend interface, Auth middleware implements the IAuthentication interface and you can get fine grained authorisation with the IAuthorization interface

Yet, we’re just beginning to tap into the potential of plugins. As we see it, Filestash is a framework for developing file management applications. Once you open up the cover, you will find a core engine wrapped with plugins that define almost every facet of the file manager.

For example, with plugins, you can not only change the default file viewer or build completly new ones from the ground up as we did with our OnlyOffice integration to support office documents. You can also alter where Filestash’s configuration is pulled from and saved. While the filesystem is the default method, plugins enable configuration via S3 or directly through environment variables. Searching capabilities go beyond the default recursive search plugin; they can be enhanced with more sophisticated FTS engines, like our SQLite implementation, integrate with your existing Elasticsearch or Solr cluster or be disabled altogether. Additionally, 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.

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

about page screenshot

To truly grasp the breadth of options available through plugins, delving into the source code is the way to go. A good starting point for this exploration is this and this.

Upgrade

To update Filestash:

~/filestash$ curl -O https://downloads.filestash.app/latest/docker-compose.yml
% 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