The personal finance app for everyone
Improve self hosting docs (#732)
Zach Gollwitzer2aee8e30271a
diff --git a/README.md b/README.mdindex 06a8a994..959135b7 100644--- a/README.md+++ b/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)--<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](docs/self-hosting/render.md)--### Docker--To host Maybe with Docker Compose, please follow our [Docker self-hosting guide](docs/self-hosting/docker.md).+1. Managed (easiest) - _coming soon..._+2. [One-click deploy](docs/hosting/one-click-deploy.md)+3. [Self-host with Docker](docs/hosting/docker.md)## Local Development Setup@@ -53,7 +52,8 @@ bin/devrake 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: `[email protected]`- 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.diff --git a/docker-compose.example.yml b/docker-compose.example.ymlindex dc9940aa..f7f1a3c1 100644--- a/docker-compose.example.yml+++ b/docker-compose.example.yml@@ -2,16 +2,20 @@ services:app:image: ghcr.io/maybe-finance/maybe:latest+ volumes:+ - ./storage:/rails/storageports:- 127.0.0.1:3000:3000restart: unless-stoppedenv_file:- .envenvironment:- DB_HOST: "postgres"- RAILS_ENV: "production"+ SELF_HOSTING_ENABLED: true+ DB_HOST: postgresRAILS_FORCE_SSL: falseRAILS_ASSUME_SSL: false+ POSTGRES_USER: postgres+ GOOD_JOB_EXECUTION_MODE: asyncdepends_on:postgres:condition: service_healthy@@ -22,8 +26,8 @@ services:volumes:- postgres-data:/var/lib/postgresql/dataenvironment:- POSTGRES_USER: ${POSTGRES_USER:?}- POSTGRES_DB: ${POSTGRES_DB:-postgres}+ POSTGRES_USER: ${POSTGRES_USER:-postgres}+ POSTGRES_DB: ${POSTGRES_DB:-maybe_production}POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}healthcheck:test: [ "CMD-SHELL", "pg_isready -U $$POSTGRES_USER" ]@@ -32,4 +36,4 @@ services:retries: 5volumes:- postgres-data:+ postgres-data:\ No newline at end of filediff --git a/docs/hosting/docker.md b/docs/hosting/docker.mdnew file mode 100644index 00000000..b16b4ffa--- /dev/null+++ b/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!+diff --git a/docs/self-hosting/render.md b/docs/hosting/one-click-deploy.mdsimilarity index 56%rename from docs/self-hosting/render.mdrename to docs/hosting/one-click-deploy.mdindex b04d11b8..25fabbcc 100644--- a/docs/self-hosting/render.md+++ b/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 upgrade2. 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".-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)).+5. You should see a section at the bottom with a "Key:Value" field+ for `SECRET_KEY_BASE`. Do NOT click "generate".+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-updatesTo 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 value5. Open your new Maybe app, click your profile, click "Self Host Settings"6. Paste your deploy hook in the settings and save7. 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)diff --git a/docs/self-hosting.md b/docs/self-hosting.mddeleted file mode 100644index 1527faeb..00000000--- a/docs/self-hosting.md+++ /dev/null@@ -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.diff --git a/docs/self-hosting/docker.md b/docs/self-hosting/docker.mddeleted file mode 100644index 68d2bd8b..00000000--- a/docs/self-hosting/docker.md+++ /dev/null@@ -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!-