~/filestash # curl https://127.0.0.1:8334/healthz
curl: (60) SSL certificate OpenSSL verify result: self-signed certificate (18)
More details here: https://curl.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the webpage mentioned above.

Once we are done with the import you will get:

~/filestash # curl https://127.0.0.1:8334/healthz
{"status": "pass"}

Note: on windows, use curl.exe instead of curl

Linux

To import the certificate:

~/filestash # sudo cp dist/data/state/certs/cert.pem /usr/local/share/ca-certificates/filestash.crt
~/filestash # sudo update-ca-certificates
Updating certificates in /etc/ssl/certs...
0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
Processing triggers for ca-certificates-java (20260311)…
done.
Updating Mono key store
Mono Certificate Store Sync - version 6.12.0.199
Populate Mono certificate store from a concatenated list of certificates.
Copyright 2002, 2003 Motus Technologies. Copyright 2004-2008 Novell. BSD licensed.

Importing into legacy system store:
I already trust 121, your new list has 122
Certificate added: O=Filestash
1 new root certificates were added to your trust store.
Import process completed.

Importing into BTLS system store:
I already trust 121, your new list has 122
Certificate added: O=Filestash
1 new root certificates were added to your trust store.
Import process completed.
Done
done.

Windows

From an Administrator command prompt, import the certificate into the machine root store with certutil:

C:\Users\filestash> certutil -addstore -f Root .\cert.pem
Root "Trusted Root Certification Authorities"
Signature matches Public Key
Certificate "O=Filestash" added to store.
CertUtil: -addstore command completed successfully.

A few months ago, the LibreOffice team announced the restarting of LibreOffice Online. The r/selfhosted thread that followed made one thing obvious: the community seems to believe self hosting office documents is a choice between Collabora and OnlyOffice. Well it isn’t.

Over the last few years, new options have become usable and the lanscape is much wider than it was a few years back. In fact, they all fall into 2 families:

1. client side options
2. server side options

Client side options

Some solutions run entirely in your browser with 0 server side components. You will find:

docx.js is a viewer only that is converting your word document into an html file that more or less looks the part. The other 2, LibreOffice wasm and docx-editor don’t just render your docs but are full fledged editors.

If you need to handle more than docx, including the god awful .doc format, LibreOffice wasm is the only game in town. It will open anything you throw at it the same way LibreOffice desktop does, because it’s literally the same codebase compiled for the browser. That power comes with a real cost. The WASM payload is around 50MB even after Brotli compression, and once it’s running it will happily chew through about 800MB of RAM for the privilege. Also, because of Spectre it requires a couple of headers to unlock SharedArrayBuffer.

docx-editor goes the other way. It only handles .docx, but it’s small and fast. The tradeoff is maturity: it’s the newest of the 3, and it hasn’t had the decades of fixes that shaped LibreOffice. Expect rougher edges which will hopefully smooth out over time.

Note: to use the Filestash plugin, put the whole zip in the plugins folder (without unzipping it!) and restart your instance.

Server side options

The gold standard for server side office editors is the WOPI protocol, a protocol made by Microsoft for third party to integrate with Office Online, and which has since taken over the self hosted world.

Microsoft being Microsoft, not everyone can integrate with Microsoft 365 for the web: you need to apply to their Cloud Storage Partner Program, and giving your users the ability to selfhost their own data is against their rules. The very first clause in their minimum requirements mandates: “1. Be a proprietary cloud storage environment owned wholly by the partner company”. That opened the door to other contenders like Collabora and Only Office:

Both can be styled so they look more like the real Microsoft word. For example using our collabora stylesheet, collabora will look like this:

Then come third party vendors who don’t have selfhosting options and requires custom integrations to be made:

• zoho office - demo
• syncfusion - demo
• apryse - demo
• the unoficial Microsoft preview:

Conclusion

There’s no single winner here, only tradeoffs that depend on your situation. If you need collaborative editing, full feature parity with Word, enterprise support, and you have the server to run it, Collabora is my pick today. If document is not where your users spend most of their time, and you’re happy covering the 95% of cases people actually hit, client side options are awesome and much lighter to operate. If you’d rather not run any of this yourself, the commercial SaaS integrators are another trade off.

To use any of these options, Filestash is sticking to its plugin based architecture, so you can use whichever integration works best for you so you can run your very own word online service

Filestash supports a number of gateways including SFTP, WebDAV, S3, MCP, and AS2. Each gateway exposes an inbound interface that speaks a specific protocol, accepting connections from clients that speak that particular protocol. Downstream of that interface, you keep your existing storage. Filestash is not where your data lives. Data stays under your control, on your own infrastructure. Filestash is just a proxy, a humble translator between different protocols.

Related Articles

SFTP Gateway

MCP Gateway

Structure of the configuration file

We already alluded to it but it’s worth repeating: the /admin/storage and /admin/settings pages are nothing but direct projections of the config.json file. This config.json file naturally splits into two parts:

1. the storage section, mapping to /admin/storage
2. the settings section, mapping to /admin/settings

PART1 - The storage page

In the config.json file, these are the fields relevant to the storage page:

{
    ...
    "connections": [ // <- (1) storage backend
        {"type": "s3", "label": "mystorage"}
    ],
    ...
    "middleware": { // <- (2) authentication middleware
        "identity_provider": {
            "type": "ldap",
            "params": "..."
        },
        "attribute_mapping": {
            "related_backend": "mystorage", // <- foreign keys to the storage backend
            "params": "..." // <- mapping rules for the storages defined in related_backend
        }
    },
    ...
}

If you visit the /admin/storage page, you will see 2 blocks:

1. Storage Backend: defines which storage you want to use, whether that’s S3, SFTP, IPFS, or anything else. In the config.json, this is the connections key which contains a list of all the storage backends you have enabled. Each entry has a label that acts as a primary key, referenced by attribute_mapping.related_backend to link authentication to that storage.
2. Authentication Middleware: optional. Without it, users see the raw login form and need to know the technical details of your storage (server address, access keys, etc.). Enable it to authenticate users through an IDP and automatically connect them to the right storage. In the config.json, this lives in the middleware section which has 2 pieces to:
   1. Configure which identity_provider to use (typically “openid”, “saml”, or “ldap”) along with the parameters for your IDP.
   2. Define an attribute_mapping to generate storage connections from the user’s identity, referencing which storage backend it should apply to.

The attribute mapping params field is a JSON string following this structure:

{
    "mystorage": {"type":"s3","access_key_id":"...","secret_access_key":"..."},
    "other": {"type":"blackhole"}
}

For the full list of fields available for each storage backend, see this guide.

PART2 - The settings page

Everything in config.json that isn’t connections or middleware belongs to the settings section. The structure is not fixed as plugins can extend it with their own configuration keys. For example, the SFTP gateway plugin adds settings for the private key and other options specific to running an SFTP service. Most plugins follow the same pattern.

If you open the config.json alongside the settings page, you will see how the JSON keys map directly to what you see in the UI:

{
   "general": {        // <- that's your first level title
       "name": ...
       ...
   },
   "features": {       // <- next first level title
       "api": {        // <- second level title
          ...
       },
       ...
   },
   ...
}

Alternative Adapters

The plugin inventory lists two alternatives to the default filesystem storage:

1. plg_config_s3: stores your configuration in an S3 bucket, which is useful for cluster wide deployments where every replica needs to share the same config.

2. plg_config_env: makes the configuration read only and self contained in a single environment variable. Generate it from an existing config with: CONFIG_JSON=$(cat config.json | base64 -w0)

Note: both of these are compiled plugins and must be built directly into the Filestash binary.

Creating your own Adapter

In line with our plugin based architecture, you can create your own configuration adapter. The approach is to write a Go generator that overrides config_state.go and implements two functions:

func LoadConfig() ([]byte, error) {
    // return the configuration as JSON
}

func SaveConfig(v []byte) error {
    // persist the JSON configuration
}

This is exactly how the adapters listed above work. The same mechanism powers undocumented variants too. For example, the AWS Marketplace build uses a custom adapter that stores config in S3 with partitioning based on the account ID, along with a few convenience features specific to that environment.

Install the Helm chart:

Expose it with TLS via cert-manager:

For production, you can manage configuration as a ConfigMap. Configure your instance through the admin console, extract the resulting config.json, then use it across all replicas:

To learn more about the structure of the config file, see the configuration guide.

Uninstall:

Note for Ingress Configuration: make sure your ingress is as transparent as possible. Some ingress providers (like traefik and nginx) enforce 60s timeout which will break large uploads or downloads. Also ensure your ingress does not try to do any kind of clever caching / buffering so the upload progress users see reflects the actual transfer to the backend, not the proxy absorbing data. The Helm chart handles this automatically for nginx ingress.

function format(responseAdminConfig, responsePublicConfig = {result : {connections: []}}) {
      const config = JSON.parse(JSON.stringify(responseAdminConfig.result, (key, val) => {
          if (val && typeof val === "object" && "label" in val && "value" in val) {
              return val.value;
          }
          return val;
      }, 2));
      config.connections = responsePublicConfig.result.connections;
      delete config.constant;
      console.log(JSON.stringify(config, null, 4))
}

step2: copy the response from /admin/api/config:

const a = {
    "status": "ok",
    "result": {
        ...
     }
}

step3: copy the response from /api/config

const b = {
    "status": "ok",
    "result": {
        ....
    }
}

step4: get your config

format(a, b);

A Filestash deployment will typically have 3 components configured to answer 1 question: “who can do what and where?” with the 3 components being: storage, authentication, and authorisation. Storage is the “where”, authentication is the “who”, and authorisation is what links them together: the “… can do what …” that sits between identity and resource.

Many platforms push RBAC as the default model. Filestash doesn’t. RBAC is overkill for simple use cases and often too blunt for complex ones. What matters is the underlying model, which is the same regardless of implementation: after authentication, Filestash receives some information about the user as part of its session. That information can be anything (AD groups included). The authorisation layer takes that identity, looks at what the user is trying to access, and runs a function that returns one of two answers: grant or deny. Formally: f(identity, resource) -> grant | deny. The guide is a tour of the various implementations of that function, of which RBAC is just one particular implementation.

Option 1: Inline access control

The simplest and most direct approach. When a user authenticates, their session is populated with attributes from your IDP. Those attributes are then used to compute access rights on the spot, expressed as a set of allowed filesystem operations: ls, cat, mkdir, mv, rm, touch, save. You can either hardcode those rights directly, or define rules that compile down to them.

From there, you can layer additional controls on top:

1. chroot jails: lock users into a specific folder, preventing navigation above it
2. allow lists: filter what is visible within the accessible tree, useful for hiding folders without denying the parent path
3. read-only folders: restrict write operations on specific paths
4. virtual filesystem: apply access rules to paths that don’t physically exist on the storage, letting you present a structure independent of what’s actually there

Option 2: RBAC

RBAC maps the authorisation function to roles: f(role) -> permissions. It’s the most widely used model, and for good reason. When your access patterns map naturally to roles, it’s clean and easy to reason about.

The practical test: take a sheet of paper and sketch your access patterns. If they summarise neatly into roles, RBAC is a good fit. If you find yourself contorting the role model to cover edge cases, it probably isn’t.

Once enabled in Filestash, it looks like this:

Given a role derived from the authentication output, you define the rules that determine what that role can access and how.

Option 3 & 4: External delegation

Sometimes you might want to externalise the whole authorisation to a third party system, which is what these two options are about:

• Option 3: plg_authorisation_cerbos: delegates to Cerbos, an open-source policy-as-code engine.
• Option 4: plg_authorisation_iam: delegates to AWS IAM.

Option 5: Custom plugin

If your use case grows in complexity and none of the above fits, you can implement the authorisation plugin yourself by implementing the same interface all the options above are built upon:

type IAuthorisation interface {
	Ls(ctx *App, path string) error
	Cat(ctx *App, path string) error
	Stat(ctx *App, path string) error
	Mkdir(ctx *App, path string) error
	Rm(ctx *App, path string) error
	Mv(ctx *App, from string, to string) error
	Save(ctx *App, path string) error
	Touch(ctx *App, path string) error
}

The interface is not about read or write, it gives you the flexibility to handle all the access patterns you might ever encounter. In all the use cases we’ve seen so far, this interface has never been defeated. If you think you have a use case that breaks it, reach out. We want to know and fix it, because our goal is to have the mother of all interfaces to model any kind of authorisation scheme.

To illustrate: we built a custom plugin for a strata management company in California. Each S3 bucket represented a unit under their management. Homeowners have read only access to their own unit but are blocked from folders containing accounting, invoices, and other management documents, which were only accessible to board and committee members with rules defined per unit. Home owners could own multiple properties and act in different roles depending on the unit. Managers had broader access, admins had full access. The edge cases were complex enough that we fully unit tested the access rules but more importantly, the underlying model never failed: given who the user is and what they are trying to access, return grant or deny.

The rule of thumb: use simple solutions for simple problems. When your use case grows complex, Filestash has the flexibility to go as far as you need.

Option 1: null: not every use case requires search. If you don’t define a search plugin, the search bar disappears entirely.

Option 2: plg_search_stateless: the default for every build. Not the most powerful option, but it’s stateless, there is no index to maintain and it makes no assumptions about where an index lives, how it gets populated, or whether there’s a cost to building one.

Option 3: plg_search_sqlitefts: the default choice for basic full-text search capabilities. The largest instance we run with this plugin indexes 55 million objects on S3 that are updated continuously by an ERP system in the background. At that scale, fine-tuning the indexer configuration matters. Under the hood the plugin runs its own crawler through four phases:

1. discovery: maps the filesystem tree and tracks new files and folders. Visits and filesystem operations are used as hints to prioritise what the crawler processes next. You can also trigger this phase via the workflow engine if you want tight control over when it runs.
2. indexing: extracts file content and feeds it into the full-text search index. There are many options for content extraction. Reach out if you need OCR or more specialised processing.
3. maintenance: keeps the index from going stale by reflecting the current state of the filesystem.
4. pause: backs off when there is nothing to do to avoid unnecessary load.

Option 4: plg_search_semanticsearch: a thin wrapper on top of plg_search_sqlitefts that uses an LLM to translate natural language queries into FTS queries, so you don’t need to be an expert in the SQLite FTS5 extension to run precise searches.

Option 5: plg_search_elasticsearch: for organisations that already have an Elasticsearch cluster and want to use it as their Filestash search backend.

Option 6: plg_search_solr: same idea as option 5, but for Solr.

Beyond these options, some plugins can also hook into the search engine to power smart folder functionality. plg_widget_recent, for example, keeps track of your activity and exposes a Recent folder that accepts natural language queries, letting users ask things like: “show me all the raw images I worked on today ordered by size”.

How to make your own search plugin: a search plugin in Filestash implements a single interface:

type ISearch interface {
	Query(ctx App, basePath string, term string) ([]IFile, error)
}

Create your own and register it by calling Hooks.Register.SearchEngine. That’s exactly how all the plugins above are built.

1. “doing things …“: the actions to run, like notifying someone over email, making an API call, etc.
2. “… when something happens”: the trigger that starts the workflow, like a webhook, a scheduled time, a file event, etc.

The general mental model is:

[trigger] -> [actionA] -> [actionB]

The trigger produces data, actions consume and transform it, each step feeding the next. To see the workflows you have set up, head to /admin/workflow:

Triggers

A trigger defines when a workflow needs to run. While we ship with standard triggers based on file events, filesystem changes, webhooks and time-based schedules, there are other niche ones for triggering workflows when you receive an email with an attachment, when a user session changes, etc.

Things get interesting when plugins create their own triggers. Take the comment plugin as an example: it has a mention-based trigger that lets you control what happens whenever somebody mentions someone else while commenting on a file, which is handy for connecting to Slack, email, or any messaging app you want to hook into.

How to make your own trigger: if you look under the hood, a trigger is nothing more than an implementation of this interface:

type ITrigger interface {
	Manifest() WorkflowSpecs
	Init() (chan ITriggerEvent, error)
}

Create your own and register it as a plugin by calling Hooks.Register.WorkflowTrigger and you are good to go. Any configuration you expose to administrators goes through the template engine, meaning admins can pass environment variables directly and your code will see the expanded result:

Actions

Actions are what run once a trigger fires. Each action receives the data produced so far, does its thing, and passes the result to the next step. Chain as many as you need. We ship with a couple standard actions to send emails and make HTTP calls but things get interesting when plugins register their own actions.

For example, the built-in full-text search engine defines its own action to rebuild the index.

How to make your own action: an action is nothing more than an implementation of this interface:

type IAction interface {
	Manifest() WorkflowSpecs
	Execute(params map[string]string, input map[string]string) (map[string]string, error)
}

Create your own in a plugin and register it by calling Hooks.Register.WorkflowAction. The input map is what the previous step passed down, params is what the admin configured, and whatever you return becomes the input for the next action.

The Sovereign File Management Solution

Secure File Sharing

Effortlessly browse, organize, and share files across all your storage solutions via one intuitive interface with bridges to expose your data via SFTP, MCP or S3 for all underlying storage platform / protocol

SSO Integration & RBAC

Filestash integrates with your corporate SSO systems like LDAP, SAML, and OIDC, providing an authentication process that's familiar to your users and trusted by your sysadmins with RBAC capabilities to control who can do what and where

Gateway

Filestash acts as a gateway to expose your files through standard protocols like SFTP, S3 or MCP, allowing your users and applications to access your data from their existing tools and applications.

White-Label Solution

Personalize Filestash's appearance to complement your company's branding. You can deploy as your own with extensive white-label capabilities to meet your business needs, and integrating with your existing systems.

Workflow Engine

The workflow engine automates processes in response to events by chaining actions. These workflows orchestrate tasks, with the ability to extend processing through the plugin system.

Extendable through plugins

Filestash's plugin-based architecture is designed for versatility, catering to diverse business needs. For specialized or custom requirements, we can develop additional plugins tailored to your specifications.

Audit & Compliance

Filestash provides extensive compliance grade audit logs that are immutable, tamper proof, traceable, timestamped and non-repudiable so you know who did what and where, while staying GDPR compliant

And Many More Features...

Put us to the test

Book a demo   Get In Touch