The personal finance app for everyone
Improve self hosting docs and UI (#870)
Zach Gollwitzerd0a15b8a9872
diff --git a/README.md b/README.mdindex 959135b7..eeda3254 100644--- a/README.md+++ b/README.md@@ -35,6 +35,11 @@ There are 3 primary ways to use the Maybe app:## Local Development Setup+**If you are trying to _self-host_ the Maybe app, stop here. You+should [read this guide to get started](docs/hosting/docker.md).**++The instructions below are for developers to get started with contributing to the app.+### Requirements- Ruby 3.3.1diff --git a/app/controllers/settings/hostings_controller.rb b/app/controllers/settings/hostings_controller.rbindex 36b9a0ee..89a42946 100644--- a/app/controllers/settings/hostings_controller.rb+++ b/app/controllers/settings/hostings_controller.rb@@ -47,7 +47,7 @@ class Settings::HostingsController < SettingsControllerendend- if hosting_params[:upgrades_mode] != "manual" && hosting_params[:render_deploy_hook].blank?+ if hosting_params[:upgrades_mode] == "auto" && hosting_params[:render_deploy_hook].blank?@errors.add(:render_deploy_hook, t("settings.hostings.update.render_deploy_hook_error"))enddiff --git a/app/views/settings/hostings/show.html.erb b/app/views/settings/hostings/show.html.erbindex 2e8dd0ae..37c1f3f6 100644--- a/app/views/settings/hostings/show.html.erb+++ b/app/views/settings/hostings/show.html.erb@@ -5,47 +5,52 @@<h1 class="text-gray-900 text-xl font-medium mb-4"><%= t(".page_title") %></h1><%= settings_section title: t(".general_settings_title") do %><%= form_with model: Setting.new, url: settings_hosting_path, method: :patch, local: true, html: { class: "space-y-6", data: { controller: "auto-submit-form", "auto-submit-form-trigger-event-value" => "blur" } } do |form| %>- <div>- <h2 class="font-medium mb-1"><%= t(".upgrades.title") %></h2>- <p class="text-gray-500 text-sm mb-4"><%= t(".upgrades.description") %></p>- <div class="space-y-4">- <div class="flex items-center gap-4">- <%= form.radio_button :upgrades_mode, "manual", checked: Setting.upgrades_mode == "manual", data: { "auto-submit-form-target" => "auto", "autosubmit-trigger-event": "input" } %>- <%= form.label :upgrades_mode_manual, t(".upgrades.manual.title"), class: "text-gray-900 text-sm" do %>- <span class="font-medium"><%= t(".upgrades.manual.title") %></span>- <br>- <span class="text-gray-500">++ <% if ENV["HOSTING_PLATFORM"] == "render" %>+ <div>+ <h2 class="font-medium mb-1"><%= t(".upgrades.title") %></h2>+ <p class="text-gray-500 text-sm mb-4"><%= t(".upgrades.description") %></p>+ <div class="space-y-4">+ <div class="flex items-center gap-4">+ <%= form.radio_button :upgrades_mode, "manual", checked: Setting.upgrades_mode == "manual", data: { "auto-submit-form-target" => "auto", "autosubmit-trigger-event": "input" } %>+ <%= form.label :upgrades_mode_manual, t(".upgrades.manual.title"), class: "text-gray-900 text-sm" do %>+ <span class="font-medium"><%= t(".upgrades.manual.title") %></span>+ <br>+ <span class="text-gray-500"><%= t(".upgrades.manual.description") %></span>- <% end %>- </div>- <div class="flex items-center gap-4">- <%= form.radio_button :upgrades_mode, "release", checked: Setting.upgrades_mode == "auto" && Setting.upgrades_target == "release", data: { "auto-submit-form-target" => "auto", "autosubmit-trigger-event": "input" } %>- <%= form.label :upgrades_mode_release, t(".upgrades.latest_release.title"), class: "text-gray-900 text-sm" do %>- <span class="font-medium"><%= t(".upgrades.latest_release.title") %></span>- <br>- <span class="text-gray-500">+ <% end %>+ </div>+ <div class="flex items-center gap-4">+ <%= form.radio_button :upgrades_mode, "release", checked: Setting.upgrades_mode == "auto" && Setting.upgrades_target == "release", data: { "auto-submit-form-target" => "auto", "autosubmit-trigger-event": "input" } %>+ <%= form.label :upgrades_mode_release, t(".upgrades.latest_release.title"), class: "text-gray-900 text-sm" do %>+ <span class="font-medium"><%= t(".upgrades.latest_release.title") %></span>+ <br>+ <span class="text-gray-500"><%= t(".upgrades.latest_release.description") %></span>- <% end %>- </div>- <div class="flex items-center gap-4">- <%= form.radio_button :upgrades_mode, "commit", checked: Setting.upgrades_mode == "auto" && Setting.upgrades_target == "commit", data: { "auto-submit-form-target" => "auto", "autosubmit-trigger-event": "input" } %>- <%= form.label :upgrades_mode_commit, t(".upgrades.latest_commit.title"), class: "text-gray-900 text-sm" do %>- <span class="font-medium"><%= t(".upgrades.latest_commit.title") %></span>- <br>- <span class="text-gray-500">+ <% end %>+ </div>+ <div class="flex items-center gap-4">+ <%= form.radio_button :upgrades_mode, "commit", checked: Setting.upgrades_mode == "auto" && Setting.upgrades_target == "commit", data: { "auto-submit-form-target" => "auto", "autosubmit-trigger-event": "input" } %>+ <%= form.label :upgrades_mode_commit, t(".upgrades.latest_commit.title"), class: "text-gray-900 text-sm" do %>+ <span class="font-medium"><%= t(".upgrades.latest_commit.title") %></span>+ <br>+ <span class="text-gray-500"><%= t(".upgrades.latest_commit.description") %></span>- <% end %>+ <% end %>+ </div></div></div>- </div>- <div>- <h2 class="font-medium mb-1"><%= t(".provider_settings.title") %></h2>- <p class="text-gray-500 text-sm mb-4"><%= t(".render_deploy_hook_description") %></p>- <%= form.url_field :render_deploy_hook, label: t(".render_deploy_hook_label"), placeholder: t(".render_deploy_hook_placeholder"), value: Setting.render_deploy_hook, data: { "auto-submit-form-target" => "auto" } %>- </div>++ <div>+ <h2 class="font-medium mb-1"><%= t(".provider_settings.title") %></h2>+ <p class="text-gray-500 text-sm mb-4"><%= t(".render_deploy_hook_description") %></p>+ <%= form.url_field :render_deploy_hook, label: t(".render_deploy_hook_label"), placeholder: t(".render_deploy_hook_placeholder"), value: Setting.render_deploy_hook, data: { "auto-submit-form-target" => "auto" } %>+ </div>+ <% end %>+<div><h2 class="font-medium mb-1"><%= t(".smtp_settings.title") %></h2><p class="text-gray-500 text-sm mb-4"><%= t(".smtp_settings.description") %></p>@@ -69,13 +74,14 @@</div></div><div>- <%= link_to t(".smtp_settings.send_test_email_button"), send_test_email_settings_hosting_path, data: { turbo_method: :post }, class:"bg-gray-50 text-gray-900 text-sm font-medium rounded-lg px-3 py-2" %>+ <%= link_to t(".smtp_settings.send_test_email_button"), send_test_email_settings_hosting_path, data: { turbo_method: :post }, class: "bg-gray-50 text-gray-900 text-sm font-medium rounded-lg px-3 py-2" %></div></div></div></div><% end %><% end %>+<div class="flex justify-between gap-4"><%= previous_setting("Billing", settings_billing_path) %><%= next_setting("Accounts", accounts_path) %>diff --git a/docker-compose.example.yml b/docker-compose.example.ymlindex f7f1a3c1..cbd5232a 100644--- a/docker-compose.example.yml+++ b/docker-compose.example.yml@@ -1,21 +1,55 @@+# ===========================================================================+# Example Docker Compose file+# ===========================================================================+#+# Purpose:+# --------+#+# This file is an example Docker Compose configuration for self hosting+# Maybe on your local machine or on a cloud VPS.+#+# The configuration below is a "standard" setup, but may require modification+# for your specific environment.+#+# Setup:+# ------+#+# To run this, you should read the setup guide:+#+# https://github.com/maybe-finance/maybe/blob/main/docs/hosting/docker.md+#+# Troubleshooting:+# ----------------+#+# If you run into problems, you should open a Discussion here:+#+# https://github.com/maybe-finance/maybe/discussions/categories/general+#+services:app:image: ghcr.io/maybe-finance/maybe:latest+volumes:- ./storage:/rails/storage+ports:- - 127.0.0.1:3000:3000+ - 3000:3000+restart: unless-stopped- env_file:- - .env+environment:- SELF_HOSTING_ENABLED: true- DB_HOST: postgres- RAILS_FORCE_SSL: false- RAILS_ASSUME_SSL: false- POSTGRES_USER: postgres+ SELF_HOSTING_ENABLED: "true"+ RAILS_FORCE_SSL: "false"+ RAILS_ASSUME_SSL: "false"GOOD_JOB_EXECUTION_MODE: async+ SECRET_KEY_BASE: ${SECRET_KEY_BASE:?}+ DB_HOST: postgres+ POSTGRES_DB: ${POSTGRES_DB:-maybe_production}+ POSTGRES_USER: ${POSTGRES_USER:-maybe_user}+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}+depends_on:postgres:condition: service_healthy@@ -26,11 +60,11 @@ services:volumes:- postgres-data:/var/lib/postgresql/dataenvironment:- POSTGRES_USER: ${POSTGRES_USER:-postgres}+ POSTGRES_USER: ${POSTGRES_USER:-maybe_user}POSTGRES_DB: ${POSTGRES_DB:-maybe_production}POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}healthcheck:- test: [ "CMD-SHELL", "pg_isready -U $$POSTGRES_USER" ]+ test: [ "CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB" ]interval: 5stimeout: 5sretries: 5diff --git a/docs/hosting/docker.md b/docs/hosting/docker.mdindex b16b4ffa..425a4c75 100644--- a/docs/hosting/docker.md+++ b/docs/hosting/docker.md@@ -1,102 +1,177 @@# Self Hosting Maybe with Docker-## Quick Start+This guide will help you setup, update, and maintain your self-hosted Maybe application with Docker Compose. Docker Compose is the most popular and recommended way to self-host the Maybe app.-_The below quickstart assumes you're running on Mac or Linux. Windows will-be different._+If you want a _less+technical_ way to host the Maybe app, you can [host on Render](/docs/hosting/one-click-deploy.md) as an+_**alternative** to Docker Compose_.-Make sure [Docker is installed](https://docs.docker.com/engine/install/) and-setup your local environment:+## Setup Guide++Follow the guide below to get your app running.++### Step 1: Install Docker++Complete the following steps:++1. Install Docker Engine by following [the official guide](https://docs.docker.com/engine/install/)+2. Start the Docker service on your machine+3. Verify that Docker is installed correctly and is running by opening up a terminal and running the following command:++```bash+# If Docker is setup correctly, this command will succeed+docker run hello-world+```++### Step 2: Configure your Docker Compose file and environnment++#### Create a directory for your app to run++Open your terminal and create a directory where your app will run. Below is an example command with a recommended directory:```bash# Create a directory on your computer for Docker filesmkdir -p ~/docker-apps/maybe++# Once created, navigate your current working directory to the new foldercd ~/docker-apps/maybe+```++#### Copy our sample Docker Compose file++Make sure you are in the directory you just created and run the following command:+```bash# Download the sample docker-compose.yml file from the Maybe Github repository-curl -o docker-compose.yml https://raw.githubusercontent.com/maybe-finance/maybe/main/docker-compose.example.yml+curl -o compose.yml https://raw.githubusercontent.com/maybe-finance/maybe/main/docker-compose.example.yml+```++This command will do the following:++1. Fetch the sample docker compose file from our public Github repository+2. Creates a file in your current directory called `compose.yml` with the contents of the example file++At this point, the only file in your current working directory should be `compose.yml`.++#### Create your environment file++In order to configure the app, you will need to create a file called `.env`, which is where Docker will read environment variables from.++To do this, run the following command:++```bash+touch .env+```++#### Generate the app secret key++The app requires an environment variable called `SECRET_KEY_BASE` to run.-# Create an .env file (make sure to fill in empty variables manually)-cat << EOF > .env-# Use "openssl rand -hex 64" to generate this-SECRET_KEY_BASE=+We will first need to generate this in the terminal. If you have `openssl` installed on your computer, you can generate it with the following command:-# Can be any value, set to what you'd like-POSTGRES_PASSWORD=-EOF+```bash+openssl rand -hex 64+```++_Alternatively_, you can generate a key without openssl or any external dependencies by pasting the following bash command in your terminal and running it:++```bash+head -c 64 /dev/urandom | od -An -tx1 | tr -d ' \n' && echo+```++Once you have generated a key, save it and move on to the next step.++#### Fill in your environment file++Open the file named `.env` that we created in a prior step using your favorite text editor.++Fill in this file with the following variables:++```txt+SECRET_KEY_BASE="replacemewiththegeneratedstringfromthepriorstep"+POSTGRES_PASSWORD="replacemewithyourdesireddatabasepassword"```-Make sure to generate your `SECRET_KEY_BASE` value and save the `.env` file.-Then you're ready to run the app, which will be available at-`http://localhost:3000` in your browser:+### Step 3: Test your app++You are now ready to run the app. Start with the following command to make sure everything is working:```bash-docker-compose up -d+docker compose up```-Lastly, go to `http://localhost:3000` in your browser, **create a new-account**, and you're ready to start tracking your finances!+This will pull our official Docker image and start the app. You will see logs in your terminal.-## Detailed Setup Guide+Open your browser, and navigate to `http://localhost:3000`.-### Prerequisites+If everything is working, you will see the Maybe login screen.-- Install Docker Engine by- following [the official guide](https://docs.docker.com/engine/install/)-- Start the Docker service on your machine+### Step 4: Create your account-### App Setup+The first time you run the app, you will need to register a new account by hitting "register" on the login page.-1. Create a new directory on your machine (we suggest something like- `$HOME/docker-apps/maybe`)-2. Create a `docker-compose.yml` file (we suggest- using [our example](/docker-compose.example.yml)- if- you're new to self-hosting and Docker)-3. Create a `.env` file and add the required variables. Currently,- `SECRET_KEY_BASE` is the only required variable, but you can take a look- at our [.env.example](/.env.example) file to see all available options.+1. Enter your email+2. Enter a password-### Run app with Docker Compose+### Step 5: Run the app in the background-1. Run `docker-compose up -d` to start the maybe app in detached mode.-2. Access the Maybe app by navigating to http://localhost:3000 in your web- browser.+Most self-hosting users will want the Maybe app to run in the background on their computer so they can access it at all times. To do this, hit `Ctrl+C` to stop the running process, and then run the following command:-### Updating the App+```bash+docker compose up -d+```-The mechanism that updates your self-hosted Maybe app is the GHCR (Github-Container Registry) Docker image that you see in the `docker-compose.yml` file:+The `-d` flag will run Docker Compose in "detached" mode. To verify it is running, you can run the following command:++```+docker compose ls+```++### Step 6: Enjoy!++Your app is now set up. You can visit it at `http://localhost:3000` in your browser.++If you find bugs or have a feature request, be sure to read through our [contributing guide here](https://github.com/maybe-finance/maybe/wiki/How-to-Contribute-Effectively-to-this-Project).++## How to update your app++The mechanism that updates your self-hosted Maybe app is the GHCR (Github Container Registry) Docker image that you see in the `docker-compose.yml` file:```ymlimage: ghcr.io/maybe-finance/maybe:latest```-We recommend using one of the following images, but you can pin your app to-whatever version you'd like (-see [packages](https://github.com/maybe-finance/maybe/pkgs/container/maybe)):+We recommend using one of the following images, but you can pin your app to whatever version you'd like (see [packages](https://github.com/maybe-finance/maybe/pkgs/container/maybe)):- `ghcr.io/maybe-finance/maybe:latest` (latest commit)- `ghcr.io/maybe-finance/maybe:stable` (latest release)-By default, your app _will NOT_ automatically update. To update your-self-hosted app, you must run the following commands:+By default, your app _will+NOT_ automatically update. To update your self-hosted app, run the following commands in your terminal:```bash-docker-compose pull # This pulls the "latest" published image from GHCR--docker-compose up -d # Restarts the app+cd ~/docker-apps/maybe # Navigate to whatever directory you configured the app in+docker compose pull # This pulls the "latest" published image from GHCR+docker compose build app # This rebuilds the app with updates+docker compose up --no-deps -d app # This restarts the app using the newest version```-#### Changing the image+## How to change which updates your app receives-If you'd like to pin the app to a specific version or tag, all you need to do is-edit the `docker-compose.yml` file:+If you'd like to pin the app to a specific version or tag, all you need to do is edit the `docker-compose.yml` file:```ymlimage: ghcr.io/maybe-finance/maybe:stable```+After doing this, make sure and restart the app:++```bash+docker compose pull # This pulls the "latest" published image from GHCR+docker compose build app # This rebuilds the app with updates+docker compose up --no-deps -d app # This restarts the app using the newest version+```+## TroubleshootingThis section will provide troubleshooting tips and solutions for common issues