Merge branch 'main' into sk/kamal-deploy

ai.md

@@ -20,7 +20,7 @@ We recommend choosing "OpenAI" unless you know you want to use a different model
 ### Configuring OpenAI
 
 If you're using OpenAI, you need to set `OPENAI_API_KEY` in your environment or settings file (`.env` in development).
-You can also change the model used by setting `OPENAI_MODEL`, which defaults to `"gpt-3.5-turbo"`.
+You can also change the model used by setting `OPENAI_MODEL`, which defaults to `"gpt-4o"`.
 
 See [this page](https://help.openai.com/en/articles/4936850-where-do-i-find-my-secret-api-key) for help
 finding your OpenAI API key.
@@ -33,7 +33,7 @@ values in your `settings.py`. For example:
 ```python
 LLM_MODELS = {
     "gpt-3.5-turbo": {"api_key": env("OPENAI_API_KEY", default="")},
-    "gpt4": {"api_key": env("OPENAI_API_KEY", default="")},
+    "gpt-4o": {"api_key": env("OPENAI_API_KEY", default="")},
     "claude-3-opus-20240229": {"api_key": env("ANTHROPIC_API_KEY", default="")},
     "ollama_chat/llama3": {"api_base": env("OLLAMA_API_BASE", default="http://localhost:11434")},  # requires a running ollama instance
 }

code-structure.md

@@ -83,7 +83,9 @@ The majority of the project's base template layouts are in the `templates/web` f
 ## Code formatting
 
 For projects that have enabled the `Autoformat code` option, the code will have been formatted
-using [black](https://black.readthedocs.io/en/stable/) and [isort](https://pycqa.github.io/isort/).
+using [ruff](https://github.com/astral-sh/ruff)—a drop-in replacement for
+[black](https://black.readthedocs.io/en/stable/) and [isort](https://pycqa.github.io/isort/) that runs
+much faster than those tools.
 
 The project will also include [pre-commit](https://pre-commit.com/) as a dependency in the requirements file
 as well as the `.pre-commit-config.yaml` file in the root directory. pre-commit is a tool for managing pre-commit
@@ -96,19 +98,18 @@ $ pre-commit install --install-hooks
 pre-commit installed at .git/hooks/pre-commit
 ```
 
-The default configuration that ships with Pegasus will run `isort` and `black` prior to every Git
+The default configuration that ships with Pegasus will run `ruff` and `ruff-format` prior to every Git
 commit. If there are fixes that are needed you will be notified in the shell output.
 
 ### pre-commit Usage
 
 **Manually running hooks**
+
 ```shell
 # run all hooks against currently staged files
 pre-commit run
 # run all the hooks against all the files. This is a useful invocation if you are using pre-commit in CI.
 pre-commit run --all-files
-# only run the isort hook against all staged files
-pre-commit run isort
 ```
 
 **Temporarily disable hooks**
@@ -120,27 +121,16 @@ For more information on using and configuring pre-commit check out the
 
 
 ### Tool configurations
-The configuration for the tools can be found in the [`pyproject.toml`][toml] file.
-
-[toml]: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#what-on-earth-is-a-pyproject-toml-file
 
-**isort**
+The configuration for the tools can be found in the [`pyproject.toml`][toml] file, using the same syntax as `black`.
 
-| Parameter    | Value   |
-|--------------|---------|
-| Filter Files | `true`  |
-| Profile      | `black` | 
-| Line Length  | `120`   |
-
-[iSort docs](https://pycqa.github.io/isort/docs/configuration/options)
-
-**black**
+[toml]: https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#what-on-earth-is-a-pyproject-toml-file
 
-| Parameter    | Value   |
-|--------------|---------|
-| Line Length  | `120`   |
+For the most part the default black/ruff formats have been preserved, with a few updates, for example,
+increasing the line length to 120.
 
-[Black docs](https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html)
+You can find more information about these values in the
+[ruff README](https://github.com/astral-sh/ruff?tab=readme-ov-file#configuration).
 
 ### Upgrading
 

configuration.md

@@ -106,8 +106,11 @@ The domain name of this `Site` will be used for your server address.
 If you need to change the URL after installation, you can go to the site admin at `admin/sites/site/` and
 modify the values accordingly, leaving off any http/https prefix.
 
-In development you'll typically want a domain name of `localhost:8000`, and in production this should
+In development, you'll typically want a domain name of `localhost:8000`, and in production this should
 be the domain where your users access your app.
+Note that this URL must match *exactly* what is in the browser address bar.
+So, for example, if you load your development site from `127.0.0.1:8000` instead of `localhost:8000` then
+that is what you should put in.
 
 **Example Development Configuration**
 
@@ -281,6 +284,20 @@ For help configuring LLMs and AIs, see the [AI docs](./ai.md).
 
 See the [celery docs](/celery) for set up and configuration of Celery.
 
+## Turnstile
+
+To enable support for [Cloudflare Turnstile](https://www.cloudflare.com/products/turnstile/),
+set `TURNSTILE_KEY` and `TURNSTILE_SECRET` in your settings or environment variables.
+
+This should automatically enable turnstile on your sign up pages.
+
+It is recommended to create two different Turnstile accounts on Cloudflare for development and production.
+In development you can specify "localhost" as your domain like this:
+
+![Turnstile Dev](/images/turnstile.png)
+
+In production, you should replace that with your site's production domain. 
+
 
 ## Mailing List
 
@@ -358,6 +375,12 @@ you to have persistent storage available for your site such as a Docker volume.
 
 ### Setting up S3 media storage
 
+*For a video walkthrough of this content (using kamal deployment), see below:*
+
+<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; height: auto; margin-bottom: 1em;">
+    <iframe src="https://www.youtube.com/embed/2n-KhVeX3og" frameborder="0" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe>
+</div>
+
 This section assumes you have set up your SaaS Pegasus project with the **S3 media file storage** enabled.
 
 In order to use S3 for media storage you will need to create an S3 bucket and provide authentication

cookbooks.md

@@ -33,9 +33,9 @@ To migrate a project from non-formatted to formatted code, you can go through th
 1. First, do a full Pegasus upgrade to the version you want to update to, as described [here](./upgrading.md).
    **Do *not* check the "autoformat" checkbox yet.**
 2. Next, run the formatting tools on your project's `main` branch: 
-   1. Install black and isort: `pip install black isort`
-   2. Run black: `black --extend-exclude migrations --line-length 120 .`
-   3. Run isort: `isort -l 120 --profile black .`
+   1. Install ruff: `pip install ruff`
+   2. Run ruff linting `ruff check --extend-exclude migrations --line-length 120 . --fix`
+   3. Run ruff formatting: `ruff format --line-length 120 .`
 3. Commit the result:
    1. `git add .`
    2. `git commit -m "apply formatting changes"`

css/tailwind.md

@@ -87,6 +87,28 @@ daisyui: {
 
 ## Other products / themes
 
+### Flowbite
+
+[Flowbite](https://flowbite.com/) is a library with many great UI components---most of which are free and open source.
+
+Flowbite can easily be added to a Pegasus project by installing it via `npm` and adding it to your global `site.js` and
+`tailwind.config.js` files.
+
+You can use [this git patch file](https://gist.github.com/czue/73cec7ff562aff0943e55538fe9b4550#file-flowbite-patch)
+as a starting point and apply it to your project by running:
+
+```
+git apply flowbite.patch
+```
+
+This demonstrates basic installation and enabling the [datepicker plugin](https://flowbite.com/docs/plugins/datepicker/).
+
+After applying the patch you will need to run `npm install` and `npm run dev-watch` to enable it on all pages.
+
+If you build with the Pegasus examples, you should be able to see the datepicker at [http://localhost:8000/pegasus/forms/](http://localhost:8000/pegasus/forms/).
+
+### Tailwind UI
+
 [Tailwind UI](https://tailwindui.com/) is a great product for building more complex pages, including marketing sites and app UIs.
 It another great option for getting help with UI components and pages, and should integrate seamlessly with the current Pegasus templates.
 

deployment/kamal.md

@@ -40,10 +40,9 @@ We'll walk through these in more detail in order below.
 The first step is to provision a server were you will host your application.
 Some popular choices include:
 
-1. Digital Ocean Droplets (you can sign up with [this link](https://m.do.co/c/432e3abb37f3) to get $100 credit
-and help support Pegasus).
-2. [Linode](https://www.linode.com/).
-3. [Hetzner](https://www.hetzner.com/).
+1. Hetzner (get €20 credit and support Pegasus with [this link](https://hetzner.cloud/?ref=49vhF1w3TIyB)).
+2. Digital Ocean Droplets (get $100 credit and support Pegasus with [this link](https://m.do.co/c/432e3abb37f3)).
+3. [Linode](https://www.linode.com/).
 4. [AWS](https://aws.amazon.com/) (Lightsail or EC2).
 5. [Google Cloud](https://cloud.google.com/).
 6. [Microsoft Azure](https://azure.microsoft.com/en-us).
@@ -496,3 +495,17 @@ In your repositories settings page, go to the "Secrets and variables -> Actions"
 
 With these secrets set, the GitHub Actions workflow will be able to deploy your app to Kamal. To test it
 go to the "Actions" tab in your repository, click on the "Kamal Deploy" workflow, and then click "Run workflow".
+
+### Cookbooks
+
+#### Changing your site URL
+
+To change your site's URL, do the following:
+
+1. Set up a new DNS endpoint as outlined above.
+2. Change all ``Host(`example.com`)`` values in your traefik configuration in `deploy.yml` to the new domain.
+3. Update your `ALLOWED_HOSTS` setting / environment variable as needed.
+4. Run `kamal traefik reboot`.
+4. Run `kamal deploy`
+
+Your app should now be running on your new domain.

deployment/production-checklist.md

@@ -51,6 +51,7 @@ Ensure that you have configured the following variables (if you are using them):
 `STRIPE_LIVE_PUBLIC_KEY`, and `STRIPE_LIVE_SECRET_KEY` config vars (or whatever subset you are using).
 - If you set up email, ensure whatever keys/secrets you need are set.
 - If you're using Mailchimp, set `MAILCHIMP_API_KEY` and `MAILCHIMP_LIST_ID`.
+- If you're using Health Checks, set `HEALTH_CHECK_TOKENS`.
 
 Refer to your [chosen platform's documentation](/deployment.rst) for details on how to set environment variables in that platform.
 
@@ -77,6 +78,21 @@ There is guidance on configuring media files in the [settings and configuration
 The most common choice of external storage is [Amazon S3](https://aws.amazon.com/s3/),
 though many cloud providers have their own S3-compatible options, e.g. [Digital Ocean Spaces](https://www.digitalocean.com/products/spaces).
 
+## Check your static file setup
+
+By default, Pegasus uses [whitenoise](https://whitenoise.readthedocs.io/en/stable/index.html) for static files.
+**If you keep the default setup, you do not need to change anything.**
+Static files will be built and collected as part of the build process of your Docker container and should be available
+on your production site.
+
+If you decide to switch to serving files externally, for example, using Amazon S3,
+then you may need to modify your static file set up for some platforms.
+This is because production secrets necessary to save files to S3 may not be available during the Docker container build.
+
+If this is the case, you should modify your deployment set up so that `python manage.py collectstatic --noinput` is run
+at the same time as Django database migrations, so that the necessary secrets are available to the application.
+The exact way to do this will vary by deployment platform.
+
 ## Optimize your front end
 
 The front-end files that ship with Pegasus are the developer-friendly versions.
@@ -94,7 +110,7 @@ The platform-specific docs have some guidance on setting this up where possible.
 ## Update other configuration options
 
 See [the configuration page](/configuration.md) for a larger list of options,
-including social login, sign up flow changes, analytics, logging, and so on.
+including social login, sign up flow changes, analytics, logging, adding captchas, and so on.
 
 ## Set up monitoring
 
@@ -104,7 +120,18 @@ see any errors that are encountered.
 It's also recommended to enable the health check endpoint and connect it to a monitoring tool
 like [StatusCake](https://www.statuscake.com/) or [Uptime Robot](https://uptimerobot.com/) so that
 you can be alerted whenever your site or services are having an outage.
-The URL you should connect is: yourdomain.com/health/.
+The URL you should connect is: `yourdomain.com/health/`.
+
+If you have the "Health Check Endpoint" option enabled for your project you should also ensure that
+you have set the `HEALTH_CHECK_TOKENS` environment variable to a secure value. This can be a comma-separated
+list of tokens that are required to access the health check endpoint:
+
+```
+yourdomain.com/health/?token=your_secret_token
+```
+
+You can then use this URL with the monitoring tool to ensure that only your monitoring tool can
+access the health check endpoint.
 
 ## Double-check your language settings
 

front-end.md

@@ -120,7 +120,7 @@ Pegasus has a few patterns for dealing with this.
 There are two "site-wide" JavaScript files used in Pegasus.
 
 The `site.js` file contains code that you want loaded *on every page*.
-It's bundle file (`site-bundle.js`) is included in your `base.html`.
+Its bundle file (`site-bundle.js`) is included in your `base.html`.
 This is a good place to put global code, library imports, etc. which should always be available.
 
 The `app.js` file contains code that you want loaded *on some pages---typically after login.