doc: env-vars

FASTN.ftd

@@ -691,6 +691,8 @@ skip: true
   document: backend/ftd-redirect.ftd
 - Using `fastn` With Django Or Other Backends: /django/
   document: backend/django.ftd
+- Enviroment Variables: /env/
+  document: backend/env-vars.ftd
 
 ## Deploy: /github-pages/
   document: author/how-to/github-pages.ftd

backend/env-vars.ftd

@@ -0,0 +1,148 @@
+-- import: fastn-community.github.io/bling/note
+
+-- ds.page: Environment Variables
+
+Environment variables are automatically loaded from your `.env` file.
+
+-- ds.h3: Automatic Environment Variables Loading with an `.env` File
+
+By default, the fastn CLI is designed to automatically load environment
+variables from an `.env` file located in the current working directory (CWD).
+
+Here's an example file:
+
+-- ds.code: .env
+lang: sh
+
+FASTN_CHECK_FOR_UPDATES=false
+FASTN_PG_URL=postgres://user:[email protected]:5432/db_name
+FASTN_GITHUB_CLIENT_ID=225b11ee49abca378769
+
+-- ds.markdown:
+
+Note that this automatic loading will not function if your
+`.env` file is committed to a **Git repository**. In such cases, the CLI will
+fail issuing a warning message.
+
+To override this behavior and intentionally use an `.env` file checked into
+Git, you can do so by setting the `FASTN_DANGER_ACCEPT_CHECKED_IN_ENV`
+environment variable.
+
+-- ds.code: Override (not recommended)
+lang: sh
+
+FASTN_DANGER_ACCEPT_CHECKED_IN_ENV=true fastn serve
+
+-- ds.h1: Supported Environment Variables
+
+`fastn` supports the following environment variables:
+
+-- ds.h2: Postrgres variables
+
+-- fastn-pg-url:
+-- fastn-pg-danger-disable-ssl:
+-- fastn-pg-ssl-mode:
+-- fastn-pg-danger-allow-unverified-certificate:
+-- fastn-pg-certificate:
+
+-- ds.h2: `fastn` cli variables
+
+-- fastn-check-for-updates:
+
+-- end: ds.page
+
+
+-- component fastn-check-for-updates:
+
+-- env-doc: `FASTN_CHECK_FOR_UPDATES`
+
+set this to true to check for updates in the background when the `fastn` cli
+runs. The cli will silently check for updates and will only log to the console
+if a new version is available.
+
+-- end: fastn-check-for-updates
+
+
+-- component fastn-pg-url:
+
+-- env-doc: `FASTN_PG_URL`
+
+The `FASTN_PG_URL` must contain a valid [connection
+string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING).
+
+This processor will not work if this environment variable is not present.
+
+-- end: fastn-pg-url
+
+
+-- component fastn-pg-danger-disable-ssl:
+
+-- env-doc: `FASTN_PG_DANGER_DISABLE_SSL`
+
+By default `fastn` connects to PostgreSQL over a secure connection. You can set
+`FASTN_PG_DANGER_DISABLE_SSL` to `false` if you want to connect to a insecure
+connection.
+
+This is not recommended in production.
+
+-- end: fastn-pg-danger-disable-ssl
+
+
+-- component fastn-pg-ssl-mode:
+
+-- env-doc: `FASTN_PG_SSL_MODE`
+
+`fastn` can connect to a PostgreSQL in a few different secure mode. See
+PostgreSQL official documentation on [SSL Mode
+Descriptions](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS).
+
+`FASTN_PG_SSL_MODE=require` is default and recommended for production.
+
+`FASTN_PG_SSL_MODE=prefer` is allowed but not recommended for production as it
+offers no benefits of encryption (is suseptible to MITM attack).
+
+`verify-ca` and `verify-full` are both better than `require`, but we do not
+support them yet because the underlying we are using, [deadpool, does not support
+it yet](https://docs.rs/deadpool-postgres/0.11.0/deadpool_postgres/enum.SslMode.html).
+We have created a [tracking issue for
+this](https://github.com/bikeshedder/deadpool/issues/277).
+
+-- end: fastn-pg-ssl-mode
+
+
+-- component fastn-pg-danger-allow-unverified-certificate:
+
+-- env-doc: `FASTN_PG_DANGER_ALLOW_UNVERIFIED_CERTIFICATE`
+
+`fastn` can ignore invalid ceritificates when connecting to PostgreSQL if you
+set `FASTN_PG_DANGER_ALLOW_UNVERIFIED_CERTIFICATE` to `true`. This is not
+recommended for production.
+
+-- end: fastn-pg-danger-allow-unverified-certificate
+
+
+-- component fastn-pg-certificate:
+
+-- env-doc: `FASTN_PG_CERTIFICATE`
+
+If you have access to root certificate of the certificate authority who issued
+the certificate used by PostgreSQL.
+
+Note that this is [not working right now when tested with
+Supabase](https://github.com/fastn-stack/fastn/issues/1383).
+
+Since this is not working, the only way to connect is by using
+`FASTN_PG_DANGER_ALLOW_UNVERIFIED_CERTIFICATE=true` right now.
+
+-- end: fastn-pg-certificate
+
+
+-- component env-doc:
+caption name:
+body content:
+
+-- ds.h3: $env-doc.name
+
+$env-doc.content
+
+-- end: env-doc

ftd-host/pg.ftd

@@ -1,6 +1,7 @@
 -- import: fastn.com/ftd/built-in-variables as v
 -- import: fastn/processors as pr
 -- import: fastn.com/ftd-host/processor
+-- import: fastn.com/backend/env-vars as env-vars
 
 
 -- ds.page: Querying PostgreSQL Using `fastn`
@@ -118,54 +119,11 @@ for: $p in $people
 
 -- ds.h1: Environment Variables
 
--- ds.h2: `FASTN_PG_URL`
-
-The `FASTN_PG_URL` must contain a valid [connection
-string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING).
-
-This processor will not work if this environment variable is not present.
-
--- ds.h2: `FASTN_PG_DANGER_DISABLE_SSL`
-
-By default `fastn` connects to PostgreSQL over a secure connection. You can set
-`FASTN_PG_DANGER_DISABLE_SSL` to `false` if you want to connect to a insecure
-connection.
-
-This is not recommended in production.
-
--- ds.h2: `FASTN_PG_SSL_MODE`
-
-`fastn` can connect to a PostgreSQL in a few different secure mode. See
-PostgreSQL official documentation on [SSL Mode
-Descriptions](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS).
-
-`FASTN_PG_SSL_MODE=require` is default and recommended for production.
-
-`FASTN_PG_SSL_MODE=prefer` is allowed but not recommended for production as it
-offers no benefits of encryption (is suseptible to MITM attack).
-
-`verify-ca` and `verify-full` are both better than `require`, but we do not
-support them yet because the underlying we are using, [deadpool, does not support
-it yet](https://docs.rs/deadpool-postgres/0.11.0/deadpool_postgres/enum.SslMode.html).
-We have created a [tracking issue for
-this](https://github.com/bikeshedder/deadpool/issues/277).
-
--- ds.h2: `FASTN_PG_DANGER_ALLOW_UNVERIFIED_CERTIFICATE`
-
-`fastn` can ignore invalid ceritificates when connecting to PostgreSQL if you
-set `FASTN_PG_DANGER_ALLOW_UNVERIFIED_CERTIFICATE` to `true`. This is not
-recommended for production.
-
--- ds.h2: `FASTN_PG_CERTIFICATE`
-
-If you have access to root certificate of the certificate authority who issued
-the certificate used by PostgreSQL.
-
-Note that this is [not working right now when tested with
-Supabase](https://github.com/fastn-stack/fastn/issues/1383).
-
-Since this is not working, the only way to connect is by using
-`FASTN_PG_DANGER_ALLOW_UNVERIFIED_CERTIFICATE=true` right now.
+-- env-vars.fastn-pg-url:
+-- env-vars.fastn-pg-danger-disable-ssl:
+-- env-vars.fastn-pg-ssl-mode:
+-- env-vars.fastn-pg-danger-allow-unverified-certificate:
+-- env-vars.fastn-pg-certificate:
 
 -- end: ds.page