filex: a self-hosted file manager you can embed

When we needed to show a client the files in an S3 bucket, we had three options. Open the cloud provider's own console, where getting the permissions right for an outside user is a project in itself. Install a full file sharing platform like Nextcloud, which is far too heavy for exposing a single folder. Or write a small file listing UI for that project, which is what we did, and by the third time it was clear this would not scale.

filex is that third option, written properly.

What it does

A self-hosted file manager that puts several storage backends behind one interface. S3 compatible storage, local disks and SMB shares all appear in the same tree. You can copy and move between them; the file streams from one backend to the other and its size is verified on arrival.

The interesting part is not the interface itself, but where you can put it:

• In the browser, as a full file manager
• As a desktop application, with folder sync and a tray icon
• Embedded inside your own application, as a component from npm
• From the command line, inside scripts

All of these run the same package. When we fix a behaviour, it is fixed in all four places. That was not a design decision made up front. It was made after living through what it costs to keep two versions of the same thing in two places.

For sharing, you can generate links that expire, that cap the number of downloads, and that require a password. It works in the other direction too: you can open a link that lets someone upload files to you. Permissions work at folder and file level, so you can expose one folder to someone without exposing anything else.

One bug, in detail

A bug tells you more about how something works than a list of features does.

We added drag and drop from the desktop application to the Windows desktop. It worked fine for a single file. Dragging a folder would download the first few files and then stop.

Our first diagnosis was wrong. Folders always stopped at a file with a Turkish name, so we looked at character encoding. There was a real problem there: the download header carried raw UTF-8 and Electron's network layer rejected it with an uncatchable exception. We fixed it. Folders still stopped.

The real cause was elsewhere. On Windows, the call that starts a drag operation is modal: while the drag is in progress, the application's JavaScript does not run at all. We were learning where the file had been dropped by watching the file system. So we were sitting in a blocked loop, waiting for an event we could never see. That is also why single files worked: we prepared those before the drag started.

The fix was to move the watcher to a worker thread. It is set up before the drag begins, it reports that it is ready, and only then does the drag start.

What this bug actually taught us is that none of our existing tests could have caught it. The drop we simulated was really just creating a directory, the test data contained no non-ASCII characters, and we performed the drop after the drag had finished. The tests were green because they were measuring the wrong thing. We fixed all of them, and added a log file while we were at it, because in a packaged Electron application nothing you write to the console goes anywhere.

Where it runs

We run three separate installations on our own infrastructure. One is the main instance we use for daily work, one is a public demo, and one runs embedded inside a platform. In other words, we use the product ourselves before recommending it to anyone.

Installation is a single container. Storage backends can be added and removed while it is running, with no restart.

If you want a look

Documentation is at docs.filex.sh. You can browse the demo without creating an account. If you would rather try it on your own server, the install guide is one page and it does not take long.

If you have questions, write to us and we will be glad to walk you through it.