mirror of
https://github.com/maybe-finance/maybe.git
synced 2025-07-18 20:59:39 +02:00
Improve self hosting docs and UI (#870)
This commit is contained in:
Zach Gollwitzer
GitHub
parent
9956a9540e
commit
d0a15b8a98
5 changed files with 221 additions and 101 deletions
|
|
@ -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.1
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ class Settings::HostingsController < SettingsController
|
|||
end
|
||||
end
|
||||
|
||||
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"))
|
||||
end
|
||||
|
||||
|
|
|
|||
|
|
@ -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) %>
|
||||
|
|
|
|||
|
|
@ -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/data
|
||||
environment:
|
||||
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: 5s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
|
|
|||
|
|
@ -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 files
|
||||
mkdir -p ~/docker-apps/maybe
|
||||
|
||||
# Once created, navigate your current working directory to the new folder
|
||||
cd ~/docker-apps/maybe
|
||||
|
||||
# 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
|
||||
|
||||
# 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=
|
||||
|
||||
# Can be any value, set to what you'd like
|
||||
POSTGRES_PASSWORD=
|
||||
EOF
|
||||
```
|
||||
|
||||
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:
|
||||
#### Copy our sample Docker Compose file
|
||||
|
||||
Make sure you are in the directory you just created and run the following command:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
# Download the sample docker-compose.yml file from the Maybe Github repository
|
||||
curl -o compose.yml https://raw.githubusercontent.com/maybe-finance/maybe/main/docker-compose.example.yml
|
||||
```
|
||||
|
||||
Lastly, go to `http://localhost:3000` in your browser, **create a new
|
||||
account**, and you're ready to start tracking your finances!
|
||||
This command will do the following:
|
||||
|
||||
## Detailed Setup Guide
|
||||
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
|
||||
|
||||
### Prerequisites
|
||||
At this point, the only file in your current working directory should be `compose.yml`.
|
||||
|
||||
- Install Docker Engine by
|
||||
following [the official guide](https://docs.docker.com/engine/install/)
|
||||
- Start the Docker service on your machine
|
||||
#### Create your environment file
|
||||
|
||||
### App Setup
|
||||
In order to configure the app, you will need to create a file called `.env`, which is where Docker will read environment variables from.
|
||||
|
||||
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.
|
||||
To do this, run the following command:
|
||||
|
||||
### Run app with Docker Compose
|
||||
```bash
|
||||
touch .env
|
||||
```
|
||||
|
||||
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.
|
||||
#### Generate the app secret key
|
||||
|
||||
### Updating the App
|
||||
The app requires an environment variable called `SECRET_KEY_BASE` to run.
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
This will pull our official Docker image and start the app. You will see logs in your terminal.
|
||||
|
||||
Open your browser, and navigate to `http://localhost:3000`.
|
||||
|
||||
If everything is working, you will see the Maybe login screen.
|
||||
|
||||
### Step 4: Create your account
|
||||
|
||||
The first time you run the app, you will need to register a new account by hitting "register" on the login page.
|
||||
|
||||
1. Enter your email
|
||||
2. Enter a password
|
||||
|
||||
### Step 5: Run the app in the background
|
||||
|
||||
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:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
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:
|
||||
|
||||
```yml
|
||||
image: 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:
|
||||
|
||||
```yml
|
||||
image: 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
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
This section will provide troubleshooting tips and solutions for common issues
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue