First draft of app deployment instructions

Author: chriscarrollsmith

docs/deployment.qmd

@@ -2,4 +2,136 @@
 title: "Deployment"
 ---
 
-## Under construction
+This application requires two services to be deployed and connected to each other:
+
+1. A PostgreSQL database (the storage layer)
+2. A FastAPI app (the application layer)
+
+There are *many* hosting options available for each of these services; this guide will cover only a few of them.
+
+## Deploying and Configuring the PostgreSQL Database
+
+### On Digital Ocean
+
+## Deploying and Configuring the FastAPI App
+
+### On Modal.com
+
+The big advantages of deploying on Modal.com are:
+1. that they offer $30/month of free credits for each user, plus generous additional free credit allotments for startups and researchers, and
+2. that it's a very user-friendly platform.
+
+The disadvantages are:
+1. that Modal is a Python-only platform and cannot run the database layer, so you'll have to deploy that somewhere else, and
+2. that you'll need to make some modest changes to the codebase to get it to work on Modal.
+
+#### Getting Started
+
+- [Sign up for a Modal.com account](https://modal.com/signup)
+- Install modal in the project directory with `uv add modal`
+- Run `uv run modal setup` to authenticate with Modal
+
+#### Setting Up Modal Secrets
+
+The application relies on environment variables stored in `.env` (like `SECRET_KEY`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `RESEND_API_KEY`, `BASE_URL`). These sensitive values should be stored securely using Modal Secrets.
+
+Create a Modal Secret (e.g., named `fastapi-webapp-secrets`) either through the Modal UI or CLI:
+```bash
+# Example using CLI
+modal secret create your-app-name-secret \
+    SECRET_KEY='your_actual_secret_key' \
+    DB_USER='your_db_user' \
+    DB_PASSWORD='your_db_password' \
+    DB_HOST='your_external_db_host' \
+    DB_PORT='your_db_port' \
+    DB_NAME='your_db_name' \
+    RESEND_API_KEY='your_resend_api_key' \
+    BASE_URL='https://your-modal-app-url' # Usually https://your-org-name--your-app-name-serve.modal.run
+```
+
+**Important:** Ensure `DB_HOST` points to your *cloud* database host address, not `localhost` or `host.docker.internal`.
+
+#### Defining the Modal Image and App
+
+Create a new Python file in the root of your project, for example, `deploy.py`. This file will define the Modal Image and the ASGI app deployment.
+
+1.  **Define the Modal Image in `deploy.py`:**
+    - Use `modal.Image` to define the container environment. Chain methods to install dependencies and add code/files.
+    - Start with a Debian base image matching your Python version (e.g., 3.13).
+    - Install necessary system packages (`libpq-dev` for `psycopg2`, `libwebp-dev` for Pillow WebP support).
+    - Install Python dependencies using `run_commands` with `uv`.
+    - Add your local Python modules (`routers`, `utils`, `exceptions`) using `add_local_python_source`.
+    - Add the `static` and `templates` directories using `add_local_dir`. The default behaviour (copying on container startup) is usually fine for development, but consider `copy=True` for production stability if these files are large or rarely change.
+
+    ```python
+    # deploy.py
+    import modal
+    import os
+
+    # Define the base image
+    image = (
+        modal.Image.debian_slim(python_version="3.13")
+        .apt_install("libpq-dev", "libwebp-dev")
+        .pip_install("uv")
+        .run_commands(
+            # Install dependencies from pyproject.toml using uv
+            # Make sure uv sync handles psycopg2 correctly with libpq-dev present
+            "uv sync --no-dev --system --compile-bytecode",
+        )
+        .add_local_python_source("routers")
+        .add_local_python_source("utils")
+        .add_local_python_source("exceptions")
+        .add_local_dir("static", remote_path="/static")
+        .add_local_dir("templates", remote_path="/templates")
+    )
+
+    # Define the Modal App
+    app = modal.App(
+        name="fastapi-webapp", # Optional: name for your Modal app
+        image=image,
+        secrets=[modal.Secret.from_name("fastapi-webapp-secrets")]
+    )
+    ```
+
+2.  **Define the ASGI App Function in `deploy.py`:**
+    - Create a function decorated with `@app.function()` and `@modal.asgi_app()`.
+    - Inside this function, import your FastAPI application instance from `main.py`.
+    - Return the FastAPI app instance.
+    - Use `@modal.concurrent()` to allow the container to handle multiple requests concurrently.
+
+    ```python
+    # deploy.py (continued)
+
+    # Define the ASGI app function
+    @app.function(
+        allow_concurrent_inputs=100 # Adjust concurrency as needed
+    )
+    @modal.asgi_app()
+    def fastapi_app():
+        # Important: Import the app *inside* the function
+        # This ensures it runs within the Modal container environment
+        # and has access to the installed packages and secrets.
+        # It also ensures the lifespan function (db setup) runs correctly
+        # with the environment variables provided by the Modal Secret.
+        from main import app as web_app
+
+        return web_app
+    ```
+
+For more information on Modal FastAPI images and applications, see [this guide](https://modal.com/docs/guide/webhooks#how-do-web-endpoints-run-in-the-cloud).
+
+#### Deploying the App
+
+1.  From your terminal, in the root directory of your project, run:
+    ```bash
+    modal deploy deploy.py
+    ```
+    Modal will build the image (if it hasn't been built before or if dependencies changed) and deploy the ASGI app. It will output a public URL (e.g., `https://your-username--your-app-name.modal.run`).
+
+2.  Once you have the public URL from Modal, make sure the `BASE_URL` variable in your Modal Secret matches this public URL. This is crucial for generating correct absolute URLs (e.g., in password reset emails). If you need to update the secret, run:
+    ```bash
+    modal secret update your-app-name-secret BASE_URL='https://your-modal-app-url'
+    ```
+    Redeploy if necessary (`modal deploy deploy.py`), although changes to secrets often take effect on subsequent container starts without a full redeploy.
+
+3.  Access the provided Modal URL in your browser. Browse the site and test the registration and password reset features to ensure database and Resend connections work correctly.