From b0d91cdbe5d4725667dcb1ddc7615d8890b4b55a Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Sat, 28 Oct 2023 12:35:47 +0530 Subject: [PATCH 1/6] doc: env-vars document https://github.com/fastn-stack/fastn/pull/1425 --- FASTN.ftd | 2 ++ best-practices/env-vars.ftd | 26 ++++++++++++++++++++++++++ 2 files changed, 28 insertions(+) create mode 100644 best-practices/env-vars.ftd diff --git a/FASTN.ftd b/FASTN.ftd index 3de061412..59ab5bb1e 100644 --- a/FASTN.ftd +++ b/FASTN.ftd @@ -662,6 +662,8 @@ skip: true document: best-practices/self-referencing.ftd - Property: /property-guidelines/ document: best-practices/property-guidelines.ftd + - Enviroment Variables: /best-practices/env-vars + document: best-practices/env-vars.ftd ## Fullstack: /dynamic-urls/ document: backend/dynamic-urls.ftd diff --git a/best-practices/env-vars.ftd b/best-practices/env-vars.ftd new file mode 100644 index 000000000..8ddb1c899 --- /dev/null +++ b/best-practices/env-vars.ftd @@ -0,0 +1,26 @@ +-- 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 `.env` Files + +By default, the fastn CLI is designed to automatically load environment +variables from an `.env` file located in the current working directory (CWD). +However, please 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 + + +-- end: ds.page + From 07fc6b27f44aa935ada021e7d4511c0b7363193e Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Tue, 31 Oct 2023 14:27:20 +0530 Subject: [PATCH 2/6] move doc to fullstack section and add `.env` file example --- FASTN.ftd | 3 +-- {best-practices => backend}/env-vars.ftd | 17 ++++++++++++++--- 2 files changed, 15 insertions(+), 5 deletions(-) rename {best-practices => backend}/env-vars.ftd (67%) diff --git a/FASTN.ftd b/FASTN.ftd index 59ab5bb1e..c25f8b553 100644 --- a/FASTN.ftd +++ b/FASTN.ftd @@ -662,8 +662,6 @@ skip: true document: best-practices/self-referencing.ftd - Property: /property-guidelines/ document: best-practices/property-guidelines.ftd - - Enviroment Variables: /best-practices/env-vars - document: best-practices/env-vars.ftd ## Fullstack: /dynamic-urls/ document: backend/dynamic-urls.ftd @@ -693,6 +691,7 @@ skip: true document: backend/ftd-redirect.ftd - Using `fastn` With Django Or Other Backends: /django/ document: backend/django.ftd +- Enviroment Variables: /backend/env-vars/ ## Deploy: /github-pages/ document: author/how-to/github-pages.ftd diff --git a/best-practices/env-vars.ftd b/backend/env-vars.ftd similarity index 67% rename from best-practices/env-vars.ftd rename to backend/env-vars.ftd index 8ddb1c899..37f49910e 100644 --- a/best-practices/env-vars.ftd +++ b/backend/env-vars.ftd @@ -4,11 +4,23 @@ Environment variables are automatically loaded from your `.env` file. --- ds.h3: Automatic Environment Variables Loading with `.env` Files +-- 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). -However, please note that this automatic loading will not function if your + +Here's an example file: + +-- ds.code: .env +lang: sh + +FASTN_CHECK_FOR_UPDATES=false +FASTN_PG_URL=postgres://user:password@172.17.0.1: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. @@ -21,6 +33,5 @@ lang: sh FASTN_DANGER_ACCEPT_CHECKED_IN_ENV=true fastn serve - -- end: ds.page From 1a80f9503444c5ffaa39cb17931a69751a8ed432 Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Tue, 31 Oct 2023 14:42:04 +0530 Subject: [PATCH 3/6] /backend/env-vars/ -> /env/ --- FASTN.ftd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/FASTN.ftd b/FASTN.ftd index c25f8b553..764b27070 100644 --- a/FASTN.ftd +++ b/FASTN.ftd @@ -691,7 +691,8 @@ skip: true document: backend/ftd-redirect.ftd - Using `fastn` With Django Or Other Backends: /django/ document: backend/django.ftd -- Enviroment Variables: /backend/env-vars/ +- Enviroment Variables: /env/ + document: backend/env-vars ## Deploy: /github-pages/ document: author/how-to/github-pages.ftd From fbfc977d8f64524c531d13640941007ab919f865 Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Wed, 1 Nov 2023 11:47:42 +0530 Subject: [PATCH 4/6] add file extension --- FASTN.ftd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/FASTN.ftd b/FASTN.ftd index 764b27070..26dd60fde 100644 --- a/FASTN.ftd +++ b/FASTN.ftd @@ -692,7 +692,7 @@ skip: true - Using `fastn` With Django Or Other Backends: /django/ document: backend/django.ftd - Enviroment Variables: /env/ - document: backend/env-vars + document: backend/env-vars.ftd ## Deploy: /github-pages/ document: author/how-to/github-pages.ftd From 0906f6915d4bf97ed565582f1bf93b84a0019026 Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Wed, 1 Nov 2023 16:46:22 +0530 Subject: [PATCH 5/6] document supported env vars --- backend/env-vars.ftd | 111 +++++++++++++++++++++++++++++++++++++++++++ ftd-host/pg.ftd | 54 +++------------------ 2 files changed, 117 insertions(+), 48 deletions(-) diff --git a/backend/env-vars.ftd b/backend/env-vars.ftd index 37f49910e..a8805d140 100644 --- a/backend/env-vars.ftd +++ b/backend/env-vars.ftd @@ -33,5 +33,116 @@ 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 diff --git a/ftd-host/pg.ftd b/ftd-host/pg.ftd index 986bdf5e0..88aaa1c59 100644 --- a/ftd-host/pg.ftd +++ b/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 From 2cbfc91aa09557d8fecba5844254bab64b617915 Mon Sep 17 00:00:00 2001 From: siddhantCodes Date: Thu, 2 Nov 2023 12:49:08 +0530 Subject: [PATCH 6/6] prserve order of pg-variables --- backend/env-vars.ftd | 18 +++++++++++++----- ftd-host/pg.ftd | 8 ++------ 2 files changed, 15 insertions(+), 11 deletions(-) diff --git a/backend/env-vars.ftd b/backend/env-vars.ftd index a8805d140..dadf82840 100644 --- a/backend/env-vars.ftd +++ b/backend/env-vars.ftd @@ -39,11 +39,7 @@ FASTN_DANGER_ACCEPT_CHECKED_IN_ENV=true fastn serve -- 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: +-- fastn-pg-variables: -- ds.h2: `fastn` cli variables @@ -146,3 +142,15 @@ body content: $env-doc.content -- end: env-doc + +-- component fastn-pg-variables: + +-- ftd.column: +-- fastn-pg-url: +-- fastn-pg-danger-disable-ssl: +-- fastn-pg-ssl-mode: +-- fastn-pg-danger-allow-unverified-certificate: +-- fastn-pg-certificate: +-- end: ftd.column + +-- end: fastn-pg-variables diff --git a/ftd-host/pg.ftd b/ftd-host/pg.ftd index 88aaa1c59..48a3b8f33 100644 --- a/ftd-host/pg.ftd +++ b/ftd-host/pg.ftd @@ -1,7 +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 +-- import: fastn.com/backend/env-vars -- ds.page: Querying PostgreSQL Using `fastn` @@ -119,11 +119,7 @@ for: $p in $people -- ds.h1: Environment Variables --- 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: +-- env-vars.fastn-pg-variables: -- end: ds.page