Implement Self-Hosted Docker Compose Setup

[zachgoll]

Overview

Self hosting with Docker compose has been a highly requested feature and we plan to support it. But due to feature prioritization, we are making this a community-led effort for the time being so we can keep pushing new features to host :). We currently offer one-click self hosting on Render which is the most "beginner friendly" way to self host and our recommended method at the time of writing.

#612 laid the groundwork for self hosting, so adding Docker compose should now have a much clearer path forward.

Requirements

Please note, these requirements are a "best guess". If you find a better way to do something or additional requirements, leave a comment on this issue so they can be added to the list below.

Tasks

• Dockerfile should be in working state for the Rails app
• A Github action that publishes Dockerfile to GHCR on every commit to main
• A compose.yml file that is production-ready
  • Compose file should reference the published Dockerfile

Possible future improvements

While some users will be installing Maybe on a self-hosted instance with many other Docker images, other users will be installing it to a fresh VPS.

It may be worth creating an install.sh or prepare.sh bash script that acts as a "wizard" to configure the machine's environment, things including (but not limited to):

• Identify distro
• Install Docker / Docker compose
• Configure ports, volumes, environment variables
• Let's Encrypt certs
• Spin up container

[e-renna]

@zachgoll Might want to reconsider the 2nd end goal. The "docker way" of upgrading an application is to redeploy the container with an updated image. E.g. for a docker stack you would do:

docker compose pull
docker compose up -d

This would pull the latest docker image from GHCR, and then redeploy the docker stack with it. Therefore, the 2nd goal is not required, but also not recommended.

The folders Maybe Finance saves data to (such as user-uploaded content), should be mapped to the host running the docker daemon (so that they are retained), while the source code of the app and all the dependency should not.

This means that every time a new version of Maybe Finance is released, the new docker image ships the updated source code along with all the required dependencies.

This does not only improve stability as the software is shipped with the right dependencies, but also would allow you to reproduce the bug easily as it would allow you to run the same environment the user encountered the bug in.

If something is not clear, just tag me and I'll be happy to give a better explanation

[e-renna]

Regarding the deployment, people should be given the docker-compose.yml file which they can pull from the repository. This allows deployment with a simple docker compose up -d.

While I understand the intent of the bash script is to ease the deployment, it actually make the deployment more complex long term. To begin with, executing piped bash script that way, is generally heavily discouraged, as you would be running a script you don't know the content of directly on the host, without any further confirmation. The user will also not configure the docker compose according to their environment requirements: environment variables, port mapping, volume/directory binding, networks etc.

The script assumes Maybe Finance would be running on a dedicated VPS. However, most self-hosters run tens of docker stacks on the same host, meaning that such deployment via bash script would likely fail due to ports being already in use.

Providing a configured docker-compose.yml file (better if there is an associated .env file for its environment variables) would allow people to be more flexible with the deployment, while also relief you from some extra work and complexities that the current approach introduces.

[zachgoll]

@e-renna appreciate the comments here! You bring up some great points and I've updated the description to reflect them.

Auto-Upgrades

I think you're spot on here that we shouldn't attempt to "self-upgrade" from within the app. I have removed that from the issue description.

I do think auto-upgrades would be nice though—do you think we should consider including an optional Ouroboros / Watchtower / (other) service in the compose file?

One-liner install script

The way I was thinking about this was more of a "wizard" experience where the end user ran the script (publicly hosted in this Github repo for full transparency/inspection) and it prompted them for required information with sensible defaults.

You're probably right that we shouldn't be shooting for 100% automation here, but it could be a nice "helper" script to setup the environment for a fresh VPS instance.

I've put this in the "Future" section—let me know if you have any ideas around what this script should and should not be responsible for.

[DomiiBunn]

Just wanted to drop a friendly note regarding this topic

It might be super handy to have a script, kind of like the setup for mailcow, right/ That way, setting up your stack becomes a breeze, and you've got everything neatly organized.

If the stack is going to be as straightforward as three simple containers, maybe adding a deploy script isn't necessary.

Sometimes keeping things simple is the best approach.

<3

[e-renna]

Auto-Upgrades

I think you're spot on here that we shouldn't attempt to "self-upgrade" from within the app. I have removed that from the issue description.

I do think auto-upgrades would be nice though—do you think we should consider including an optional Ouroboros / Watchtower / (other) service in the compose file?

Auto upgrades are a nice perk, but they do introduce complexities and often result in unwanted results. Let's suppose you ship a new release with a breaking change, watchtower will update the application and render it unusable. The best approach, which is how Immich (a popular self hosted app) is to just show a popup to the admin upon login.

That said, you can still include watchtower, but it should be a non -recommended optional due to the above.

One-liner install script

The way I was thinking about this was more of a "wizard" experience where the end user ran the script (publicly hosted in this Github repo for full transparency/inspection) and it prompted them for required information with sensible defaults.

You're probably right that we shouldn't be shooting for 100% automation here, but it could be a nice "helper" script to setup the environment for a fresh VPS instance.

I've put this in the "Future" section—let me know if you have any ideas around what this script should and should not be responsible for.

Such script would have to do the following:

• Understand the distro in use
• Install the right docker repository for the distro
• Install docker and docker compose
• Ask the user the ports, volumes/directories to use
• Allow to configure environment variables
• Ask for the domain the app will be reachable from
• Perhaps generate a Let's Encrypt cert (better if handled by Maybe directly)
• Spin up the container

There is probably a few missing steps which I am sure other member of the community will be able to come up with.

In addition to the current plans, it might be worth giving a shot to Podman too as it now comes as a drop in replacement for docker in RedHat based distros.

[Radu-C-Martin]

Auto upgrades are a nice perk, but they do introduce complexities and often result in unwanted results. Let's suppose you ship a new release with a breaking change, watchtower will update the application and render it unusable. The best approach, which is how Immich (a popular self hosted app) is to just show a popup to the admin upon login.

That said, you can still include watchtower, but it should be a non -recommended optional due to the above.

Just bringing my two cents into this, but keeping it as simple as possible would be a solution that works for most people. Tagging the latest images in the default compose file allows the people that do it manually to just docker compose pull when they get the pop-up, and those who manage their versioning by themselves will just integrate it with their existing system (be it watchtower, renovate, etc. ) without too much overhead.

[zachgoll]

@e-renna awesome, thanks for the clarification on these points. I like the idea of a popup a lot.

@Radu-C-Martin noted!

It sounds like a minimalist Docker setup is what is preferred here, so I've pared down the description to reflect this.

[zachgoll]

Done via #640