Improve self hosting docs (#732)

README.md

@@ -3,36 +3,35 @@
 
 # Maybe: The OS for your personal finances
 
-<b>Get involved: [Discord](https://link.maybe.co/discord) • [Website](https://maybe.co) • [Issues](https://github.com/maybe-finance/maybe/issues)</b>
+<b>Get
+involved: [Discord](https://link.maybe.co/discord) • [Website](https://maybe.co) • [Issues](https://github.com/maybe-finance/maybe/issues)</b>
 
-_If you're looking for the previous React codebase, you can find it at [maybe-finance/maybe-archive](https://github.com/maybe-finance/maybe-archive)._
+_If you're looking for the previous React codebase, you can find it
+at [maybe-finance/maybe-archive](https://github.com/maybe-finance/maybe-archive)._
 
 ## Backstory
 
-We spent the better part of 2021/2022 building a personal finance + wealth management app called, Maybe. Very full-featured, including an "Ask an Advisor" feature which connected users with an actual CFP/CFA to help them with their finances (all included in your subscription).
+We spent the better part of 2021/2022 building a personal finance + wealth
+management app called, Maybe. Very full-featured, including an "Ask an Advisor"
+feature which connected users with an actual CFP/CFA to help them with their
+finances (all included in your subscription).
 
 The business end of things didn't work out, and so we shut things down mid-2023.
 
-We spent the better part of $1,000,000 building the app (employees + contractors, data providers/services, infrastructure, etc.).
+We spent the better part of $1,000,000 building the app (employees +
+contractors, data providers/services, infrastructure, etc.).
 
-We're now reviving the product as a fully open-source project. The goal is to let you run the app yourself, for free, and use it to manage your own finances and eventually offer a hosted version of the app for a small monthly fee.
+We're now reviving the product as a fully open-source project. The goal is to
+let you run the app yourself, for free, and use it to manage your own finances
+and eventually offer a hosted version of the app for a small monthly fee.
 
-## Self Hosting
+## Maybe Hosting
 
-You can find [detailed setup guides for self hosting here](docs/self-hosting.md).
+There are 3 primary ways to use the Maybe app:
 
-### One-Click Render deploy (recommended)
+1. Managed (easiest) - _coming soon..._
-
+2. [One-click deploy](docs/hosting/one-click-deploy.md)
-<a href="https://render.com/deploy?repo=https://github.com/maybe-finance/maybe">
+3. [Self-host with Docker](docs/hosting/docker.md)
-<img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render" />
-</a>
-
-1. Click the button above
-2. Follow the instructions in the [Render self-hosting guide](docs/self-hosting/render.md)
-
-### Docker
-
-To host Maybe with Docker Compose, please follow our [Docker self-hosting guide](docs/self-hosting/docker.md).
 
 ## Local Development Setup
 
@@ -53,7 +52,8 @@ bin/dev
 rake demo_data:reset
 ```
 
-And visit http://localhost:3000 to see the app. You can use the following credentials to log in (generated by DB seed):
+And visit http://localhost:3000 to see the app. You can use the following
+credentials to log in (generated by DB seed):
 
 - Email: `user@maybe.local`
 - Password: `password`
@@ -64,38 +64,52 @@ For further instructions, see guides below.
 
 If you'd like multi-currency support, there are a few extra steps to follow.
 
-1. Sign up for an API key at [Synth](https://synthfinance.com). It's a Maybe product and the free plan is sufficient for basic multi-currency support.
+1. Sign up for an API key at [Synth](https://synthfinance.com). It's a Maybe
+   product and the free plan is sufficient for basic multi-currency support.
 2. Add your API key to your `.env` file.
 
 ### Setup Guides
 
 #### Dev Container (optional)
 
-This is 100% optional and meant for devs who don't want to worry about installing requirements manually for their platform. You can follow [this guide](https://code.visualstudio.com/docs/devcontainers/containers) to learn more about Dev Containers.
+This is 100% optional and meant for devs who don't want to worry about
+installing requirements manually for their platform. You can
+follow [this guide](https://code.visualstudio.com/docs/devcontainers/containers)
+to learn more about Dev Containers.
 
-If you run into `could not connect to server` errors, you may need to change your `.env`'s `DB_HOST` environment variable value to `db` to point to the Postgres container.
+If you run into `could not connect to server` errors, you may need to change
+your `.env`'s `DB_HOST` environment variable value to `db` to point to the
+Postgres container.
 
 #### Mac
 
-Please visit our [Mac dev setup guide](https://github.com/maybe-finance/maybe/wiki/Mac-Dev-Setup-Guide).
+Please visit
+our [Mac dev setup guide](https://github.com/maybe-finance/maybe/wiki/Mac-Dev-Setup-Guide).
 
 #### Linux
 
-Please visit our [Linux dev setup guide](https://github.com/maybe-finance/maybe/wiki/Linux-Dev-Setup-Guide).
+Please visit
+our [Linux dev setup guide](https://github.com/maybe-finance/maybe/wiki/Linux-Dev-Setup-Guide).
 
 #### Windows
 
-Please visit our [Windows dev setup guide](https://github.com/maybe-finance/maybe/wiki/Windows-Dev-Setup-Guide).
+Please visit
+our [Windows dev setup guide](https://github.com/maybe-finance/maybe/wiki/Windows-Dev-Setup-Guide).
 
 ### Testing Emails
 
-In development, we use `letter_opener` to automatically open emails in your browser. When an email sends locally, a new browser tab will open with a preview.
+In development, we use `letter_opener` to automatically open emails in your
+browser. When an email sends locally, a new browser tab will open with a
+preview.
 
 ## Contributing
 
-Before contributing, you'll likely find it helpful to [understand context and general vision/direction](https://github.com/maybe-finance/maybe/wiki).
+Before contributing, you'll likely find it helpful
+to [understand context and general vision/direction](https://github.com/maybe-finance/maybe/wiki).
 
-Once you've done that, please visit our [contributing guide](https://github.com/maybe-finance/maybe/blob/main/CONTRIBUTING.md) to get started!
+Once you've done that, please visit
+our [contributing guide](https://github.com/maybe-finance/maybe/blob/main/CONTRIBUTING.md)
+to get started!
 
 ## Repo Activity
 
@@ -103,4 +117,6 @@ Once you've done that, please visit our [contributing guide](https://github.com/
 
 ## Copyright & license
 
-Maybe is distributed under an [AGPLv3 license](https://github.com/maybe-finance/maybe/blob/main/LICENSE). "Maybe" is a trademark of Maybe Finance, Inc.
+Maybe is distributed under
+an [AGPLv3 license](https://github.com/maybe-finance/maybe/blob/main/LICENSE). "
+Maybe" is a trademark of Maybe Finance, Inc.

docker-compose.example.yml

@@ -2,16 +2,20 @@ services:
 
   app:
     image: ghcr.io/maybe-finance/maybe:latest
+    volumes:
+      - ./storage:/rails/storage
     ports:
       - 127.0.0.1:3000:3000
     restart: unless-stopped
     env_file:
       - .env
     environment:
-      DB_HOST: "postgres"
+      SELF_HOSTING_ENABLED: true
-      RAILS_ENV: "production"
+      DB_HOST: postgres
       RAILS_FORCE_SSL: false
       RAILS_ASSUME_SSL: false
+      POSTGRES_USER: postgres
+      GOOD_JOB_EXECUTION_MODE: async
     depends_on:
       postgres:
         condition: service_healthy
@@ -22,8 +26,8 @@ services:
     volumes:
       - postgres-data:/var/lib/postgresql/data
     environment:
-      POSTGRES_USER: ${POSTGRES_USER:?}
+      POSTGRES_USER: ${POSTGRES_USER:-postgres}
-      POSTGRES_DB: ${POSTGRES_DB:-postgres}
+      POSTGRES_DB: ${POSTGRES_DB:-maybe_production}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}
     healthcheck:
       test: [ "CMD-SHELL", "pg_isready -U $$POSTGRES_USER" ]

docs/hosting/docker.md

@@ -0,0 +1,104 @@
+# Self Hosting Maybe with Docker
+
+## Quick Start
+
+_The below quickstart assumes you're running on Mac or Linux. Windows will
+be different._
+
+Make sure [Docker is installed](https://docs.docker.com/engine/install/) and
+setup your local environment:
+
+```bash
+# Create a directory on your computer for Docker files
+mkdir -p ~/docker-apps/maybe
+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:
+
+```bash
+docker-compose up -d
+```
+
+Lastly, go to `http://localhost:3000` in your browser, **create a new
+account**, and you're ready to start tracking your finances!
+
+## Detailed Setup Guide
+
+### Prerequisites
+
+- Install Docker Engine by
+  following [the official guide](https://docs.docker.com/engine/install/)
+- Start the Docker service on your machine
+
+### App Setup
+
+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.
+
+### Run app with Docker Compose
+
+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.
+
+### Updating the 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)):
+
+- `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:
+
+```bash
+docker-compose pull # This pulls the "latest" published image from GHCR
+
+docker-compose up -d # Restarts the app
+```
+
+#### Changing the image
+
+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
+```
+
+## Troubleshooting
+
+This section will provide troubleshooting tips and solutions for common issues
+encountered during deployment. Check back later for updates!
+

docs/hosting/one-click-deploy.md

@@ -1,24 +1,32 @@
-# Self Hosting Maybe on Render
+# Deploy Maybe in One Click
 
-Welcome to the self hosting guide for Maybe on [Render](https://render.com/)!
+Below are our "one-click deploy" options for running Maybe in the cloud:
 
-Render is our _recommended_ option for hosting Maybe:
+## Render
+
+Welcome to the one-click deploy guide for Maybe on [Render](https://render.
+com/)!
+
+Render is a hosting platform with a generous free tier and makes it easy to get
+started with Maybe:
 
 - Getting started is FREE
 - Up and running in <5 minutes
 - Your Maybe app is automatically deployed to a live URL
 
-## Estimated Costs
+### Estimated Costs
 
 - FREE to _get up and running_
-- $7 per month for a basic app (Render requires you to upgrade your database to keep using it)
+- $7 per month for a basic app (Render requires you to upgrade your database to
+  keep using it)
 - $14+ per month for optimal performance
 
-_**IMPORTANT:** if you plan to host Maybe on Render long-term, you MUST upgrade your database to a paid Render service._
+_**IMPORTANT:** if you plan to host Maybe on Render long-term, you MUST upgrade
+your database to a paid Render service._
 
-## Instructions
+### Instructions
 
-### Step 1: Create Render Blueprint
+#### Step 1: Create Render Blueprint
 
 <a href="https://render.com/deploy?repo=https://github.com/maybe-finance/maybe">
 <img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render" />
@@ -28,43 +36,56 @@ _**IMPORTANT:** if you plan to host Maybe on Render long-term, you MUST upgrade
 2. Sign in or create your account with Render (FREE)
 3. Give your blueprint a name (we suggest `Maybe`)
 4. Select the `main` branch
-5. You should see a section at the bottom with a "Key:Value" field for `SECRET_KEY_BASE`. Do NOT click "generate".
+5. You should see a section at the bottom with a "Key:Value" field
-6. On your computer, open a terminal and make sure you have the [openssl](https://github.com/openssl/openssl) utility installed on your computer. You can run `openssl --version` to verify it is installed.
+   for `SECRET_KEY_BASE`. Do NOT click "generate".
-7. Generate your `SECRET_KEY_BASE` by running the following command in your terminal: `openssl rand -hex 64` ([docs](https://www.openssl.org/docs/man1.1.1/man1/rand.html)).
+6. On your computer, open a terminal and make sure you have
+   the [openssl](https://github.com/openssl/openssl) utility installed on your
+   computer. You can run `openssl --version` to verify it is installed.
+7. Generate your `SECRET_KEY_BASE` by running the following command in your
+   terminal: `openssl rand -hex 64` ([docs](https://www.openssl.org/docs/man1.1.1/man1/rand.html)).
 8. Do NOT share this value with anyone.
-9. Go back to your browser and paste this value in the "Value" field for `SECRET_KEY_BASE`
+9. Go back to your browser and paste this value in the "Value" field
+   for `SECRET_KEY_BASE`
 10. Click "Apply". This will take a few minutes.
-11. Once complete, click on the `maybe` "Web Service". You should see a custom URL in the format `https://maybe-abcd.onrender.com`. Click on it, and you'll see your running Maybe app!
+11. Once complete, click on the `maybe` "Web Service". You should see a custom
+    URL in the format `https://maybe-abcd.onrender.com`. Click on it, and you'll
+    see your running Maybe app!
 
-### Step 2: Add your deploy hook for auto-updates
+#### Step 2: Add your deploy hook for auto-updates
 
 To get new releases, you will need to add your deploy hook to the app.
 
 1. Click on the `maybe` "Web Service"
 2. Click "Settings"
-3. Scroll down to the end of the "Build and Deploy" section until you find the "Deploy Hook"
+3. Scroll down to the end of the "Build and Deploy" section until you find the "
+   Deploy Hook"
 4. Copy this value
 5. Open your new Maybe app, click your profile, click "Self Host Settings"
 6. Paste your deploy hook in the settings and save
 7. You're all set!
 
-### Step 3 (IMPORTANT!!!): Upgrade your Render services
+#### Step 3 (IMPORTANT!!!): Upgrade your Render services
 
-By default, we set you up with a FREE Render web service and a FREE postgres database. We do this for a few reasons:
+By default, we set you up with a FREE Render web service and a FREE postgres
+database. We do this for a few reasons:
 
 - It allows you to take self-hosted Maybe for a FREE test-drive
 - It prevents newcomers from incurring unexpected hosting charges
 
-#### Upgrade your Database (REQUIRED)
+##### Upgrade your Database (REQUIRED)
 
-All FREE Render databases **will be deleted after a few months**. This means that **you will lose all of your Maybe data**.
+All FREE Render databases **will be deleted after a few months**. This means
+that **you will lose all of your Maybe data**.
 
-**To avoid losing data, you MUST upgrade your Render database** (a "starter" instance is $7/month)
+**To avoid losing data, you MUST upgrade your Render database** (a "starter"
+instance is $7/month)
 
 You can upgrade your instance directly in the Render dashboard.
 
-#### Upgrade your Web Service (RECOMMENDED)
+##### Upgrade your Web Service (RECOMMENDED)
 
-All FREE Render web services use a small amount of memory and "sleep" after periods of inactivity.
+All FREE Render web services use a small amount of memory and "sleep" after
+periods of inactivity.
 
-For the _fastest_ Maybe experience, you should upgrade your web service (a "starter" instance is $7/month)
+For the _fastest_ Maybe experience, you should upgrade your web service (a "
+starter" instance is $7/month)

docs/self-hosting.md

@@ -1,25 +0,0 @@
-The fastest way to get your own version of Maybe running is a "one-click deploy". Below are the currently supported platforms:
-
-## One-Click Deploys
-
-### Render (recommended)
-
-<a href="https://render.com/deploy?repo=https://github.com/maybe-finance/maybe">
-<img src="https://render.com/images/deploy-to-render-button.svg" alt="Deploy to Render" />
-</a>
-
-1. Click the button above
-2. Follow the instructions in the [Render self-hosting guide](self-hosting/render.md)
-
-## Docker
-
-**Estimated cost:** $5-15 per month
-
-Please see the [Docker self-hosting guide](self-hosting/docker.md) for detailed setup instructions.
-
-## Self hosting disclaimer
-
-While we attempt to provide cost-effective deployment options, please remember,
-**self-hosting _may_ incur monthly charges on your hosting platform of
-choice**. While we provide cost estimates for each deployment option, it is
-your responsibility to manage these costs.

docs/self-hosting/docker.md

@@ -1,75 +0,0 @@
-# Self Hosting Maybe with Docker
-
-## Quick Start
-
-To quickly get the Maybe app up and running, follow these steps:
-
-* clone the maybe repository to your local machine.
-* navigate to the repository's root directory.
-* copy the `.env.example` file to `.env` and configure the necessary
-environment variables. Edit the `SELF_HOSTING_ENABLED` and `SECRET_KEY_BASE`
-variables. You might want to edit the `DB_HOST`, `DB_PORT`,
-`POSTGRES_PASSWORD`, `POSTGRES_USER` variables as well.
-* run `docker-compose up -d` to start the maybe app in detached mode.
-* access the maybe app by navigating to http://localhost:3000 in your web browser.
-
-## Prerequisites and Setup
-
-Install Docker on your machine by following the appropriate guide for your
-operating system. If you need a GUI, install [Docker
-Desktop](https://docs.docker.com/desktop/), otherwise innstall [Docker
-Engine](https://docs.docker.com/engine/install/) (recommended for production).
-
-Next, follow these steps (shared between docker-compose and standalone):
-
-* clone the maybe repository to your local machine.
-* navigate to the repository's root directory.
-* copy the `.env.example` file to `.env` and configure the necessary
-environment variables. Edit the `SELF_HOSTING_ENABLED` and `SECRET_KEY_BASE`
-variables. You might want to edit the `DB_HOST`, `DB_PORT`,
-`POSTGRES_PASSWORD`, `POSTGRES_USER` variables as well.
-
-### Running the app with docker compose
-
-* run `docker-compose up -d` to start the maybe app in detached mode.
-* access the maybe app by navigating to http://localhost:3000 in your web browser.
-
-### Running the standalone container
-
-* run the `maybe` docker container
-
-```bash
-docker run -d \
-    --name app \
-    -p 3000:3000 \
-    --restart unless-stopped \
-    --env-file .env \
-    -e RAILS_ENV=production \
-    -e RAILS_FORCE_SSL=false \
-    -e RAILS_ASSUME_SSL=false \
-    ghcr.io/maybe-finance/maybe:latest
-```
-
-## Updating the App
-
-To update the Maybe app to the latest version, follow these steps:
-
-* Pull the latest changes from the Maybe repository if running the container in
-standalone mode.
-* If using Docker Compose, update the image field in the docker-compose.yml
-file to point to the new Docker image version (not needed if running on the
-`latest` tag, docker will automatically pull the latest image).
-* Run `docker-compose pull` to pull the latest Docker image.
-* Restart the Maybe app container using `docker-compose up -d`.
-
-## Where should I host?
-
-### Commercial VPS
-### One-Click VPS
-### Standalone Image
-
-## Troubleshooting 
-
-This section will provide troubleshooting tips and solutions for common issues
-encountered during deployment. Check back later for updates!
-