A Docker development environment for Filestash

What is Filestash?

Filestash is a web file manager that works with many different storage solutions. It provides a way to view, and often interact with the files from a web browser.

I was recently looking for an open-source solution to interact with s3 storage and some AI powered browser suggested Filestash, while it was not exactly what I was looking for I decided to give it a try.

I was pleasantly surprised about its simplicity, and it actually worked out-of-the-box, locally, for my very simple use case. Then I started exploring how to actually deploy it somewhere publicly accessible and that's when the problems started, sort of...

Why do I need a dev environment?

The preconfigured image works very well for a simple scenario, and it can easily be used locally, but then you may realize it has many things you don't need and it may not have some of the things you want. To customize your instance is a bit more difficult since documentation is not updated and some things that appear in the official docs are not actually open-source, and only available for paid customers. That being said, I totally understand the reason for those decisions, particularly nowadays.

So Filestash may not be the best solution if you need something quick that just works, but I like the philosophy behind it, even if I am not in love with the architecture, so I think it is worth to invest a little time exploring and, ideally, supporting the project.

We need a dev-environment even to do little changes like adding or removing plugins, but also to get a better idea of how it works and what can be done.

A simple development environment

Since Filestash already provided a docker image I thought it would be very straightforward for me and other users to move in that direction, also I am not a fan of local development, not for my regular tools, but even less if the development is in a language I don't use that often.

The image provided in Filestash repository has a two problems for development:

• It uses several stages. That makes sense for deployment, but not for development.
• It clones the repository instead of using the local files, so it is harder to edit and compile to see the changes.

Here is the Containerfile I used, I actually used podman instead of docker.

FROM docker.io/golang:1.25.2-trixie
WORKDIR /app
RUN apt-get update > /dev/null && \
    apt-get install -y curl make > /dev/null 2>&1 && \
    apt-get install -y libjpeg-dev libtiff-dev libpng-dev libwebp-dev libraw-dev libheif-dev libgif-dev libvips-dev > /dev/null 2>&1
EXPOSE 8334

As you can see I didn't copy the files, I just used the latest golang image but referred to it by full version to avoid problems later when it is not latest anymore, and installed all the dependencies required in the original file, I installed the ones in the compile step which are not the same from the running container, for example, I didn't install ffmpeg, since it is not a feature I care about.

Then to build the image use:

podman build -t filestash-dev:20251013 -f docker/Containerfile.filestash-dev

There are two things to notice. First, I prefer to use the date in the versioning of my dev images but it can be named and versioned at will, second, the same applies for the Containerfile it is just a matter of personal preference.

Now we can run the service, for that the following line is used:

podman run -it -v .:/app -p 8334:8334 filestash-dev:20251013 /bin/bash

Again, there are a few important things to discuss:

• Current local directory is mounted in /app, it is the same as the used in WORKDIR for convenience. The output will be created in the same directory, so it will exist even after the container is destroyed, but the cache used to build won't.
• We need to include the port in which our service will run so it is reachable outside of the container.
• I executed /bin/bash so I can run the commands in the terminal inside the container. I actually use VSCode to edit the code but locally, not inside the container. These days there are many ways to do it and container integration in VSCode is great, but it is up to you to decide the best workflow.

Afterthoughts

This is just a very quick and simple configuration, there are some shortcomings, at least for me, like being able to keep the bash history, which is not hard to do using container volumes, but it is a good starting point that leaves things open enough to suit several workflows.