Merge pull request #724 from logto-io/log-2343-log-introduction

docs: init introduction

.vscode/settings.json

@@ -19,5 +19,14 @@
   ],
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": true,
-  }
+  },
+  "cSpell.words": [
+    "Alipay",
+    "CIAM",
+    "Logto",
+    "oidc",
+    "Passwordless",
+    "silverhand",
+    "slonik"
+  ]
 }

packages/core/src/env-set/create-pool-by-env.ts

@@ -32,7 +32,7 @@ const inquireForLogtoDsn = async (key: string): Promise<[Optional<string>, boole
     type: 'confirm',
     name: 'value',
     default: false,
-    message: 'Do you have an empty databse for Logto?',
+    message: 'Do you have an empty database for Logto?',
   });
 
   const dsnAnswer = await inquirer.prompt({

packages/core/src/env-set/index.ts

@@ -19,12 +19,12 @@ const loadEnvValues = async () => {
   return Object.freeze({
     isTest,
     isProduction,
-    isHttpsEnabled: Boolean(process.env.HTTPS_CERT && process.env.HTTPS_KEY),
+    isHttpsEnabled: Boolean(process.env.HTTPS_CERT_PATH && process.env.HTTPS_KEY_PATH),
-    httpsCert: process.env.HTTPS_CERT,
+    httpsCert: process.env.HTTPS_CERT_PATH,
-    httpsKey: process.env.HTTPS_KEY,
+    httpsKey: process.env.HTTPS_KEY_PATH,
     port,
     developmentUserId: getEnv('DEVELOPMENT_USER_ID'),
-    trustingTlsOffloadingProxies: getEnv('TRUSTING_TLS_OFFLOADING_PROXIES') === 'true',
+    trustProxyHeader: getEnv('TRUST_PROXY_HEADER') === 'true',
     password: await loadPasswordValues(isTest),
     oidc: await loadOidcValues(port),
   });

packages/core/src/env-set/oidc.ts

@@ -24,7 +24,7 @@ const readPrivateKey = async (): Promise<string> => {
     return privateKey;
   }
 
-  const privateKeyPath = getEnv('OIDC_PRIVATE_KEY_PATH', 'oidc-private-key.pem');
+  const privateKeyPath = getEnv('OIDC_PRIVATE_KEY_PATH', './oidc-private-key.pem');
 
   try {
     return readFileSync(privateKeyPath, 'utf-8');

packages/core/src/index.ts

@@ -18,7 +18,7 @@ import initI18n from './i18n/init';
   try {
     await envSet.load();
     const app = new Koa({
-      proxy: envSet.values.trustingTlsOffloadingProxies,
+      proxy: envSet.values.trustProxyHeader,
     });
     await initConnectors();
     await initI18n();

packages/docs/docs/tutorial/README.md

@@ -4,4 +4,52 @@ sidebar_position: 1
 
 # Introduction
 
-🤘 Logto is an open-source customer identity solution.
+🤘 Logto helps you quickly focus on everything after signing in with the following components:
+
+- All-platform user sign-in / sign-up experience with SDK support (SPA, iOS and Android)
+- Passwordless (SMS / Email) support
+- Out-of-box social sign in support (GitHub, Google, WeChat, Alipay, etc.)
+- A web UI to control all above (Admin Console)
+- Extendable multi-language support
+- Easy deployment
+
+Boringly, we call it "[customer identity access management](https://en.wikipedia.org/wiki/Customer_identity_access_management)" (CIAM) or "customer identity solution."
+
+## Get Started
+
+### Prerequisites
+
+- NodeJS >= 16.0.0
+- PostgreSQL >= 14.0.0
+
+We recommend using a new empty database which is dedicated for Logto, while it's not a hard requirement.
+
+:::tip
+It's okay that your PostgreSQL instance is not in the same machine as NodeJS (e.g. containers + remote database environment).
+:::
+
+### Run a Logto Instance
+
+#### Download Script
+
+In your terminal:
+
+```bash
+node -e "$(printf "%s" "$(curl -fsSL https://raw.githubusercontent.com/logto-io/logto/master/install.js)")"
+```
+
+The script will download Logto and create a directory `logto` in the location you ran it. After answering [several simple questions](./configuration#questions), you will see the message like:
+
+```bash
+Server is listening to port 3001
+```
+
+Heading to http://localhost:3001 to continue the Logto journey. Enjoy!
+
+#### Docker
+
+TBD
+
+### Configuration
+
+Logto uses environment variables for configuration, along with `.env` file support. See [Configuration](./configuration) for detailed usage and full variable list.

packages/docs/docs/tutorial/configuration.md

@@ -0,0 +1,78 @@
+---
+sidebar_position: 2
+---
+
+# Configuration
+
+## Usage
+
+Logto handles environment variables in the following order:
+
+- The `.env` file in the project root, which conforms with [dotenv](https://github.com/motdotla/dotenv#readme) format
+- System environment variable
+
+Thus the system environment variable will override the value in `.env`.
+
+## First-time Setup Questions {#questions}
+
+For the first time you start Logto with no related environment variable, unless `--no-inquiry` is specified, it'll ask several questions for a smooth experience to fulfill the minimum requirements:
+
+- If you'd like to generate a private key for the OIDC provider
+- If you'd like to set up a new Logto database
+- Enter the [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6)
+
+Most of them are simple yes / no questions, or you can just go with the default value, except the [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6).
+
+The generated private key for the OIDC provider will locate on `./oidc-private-key.pem`, while other values will append to `./.env`.
+
+:::note
+The `--no-inquiry` parameter is appended by default in the Docker image.
+:::
+
+## Variable List
+
+### General
+
+| Key                | Default Value            | Type                                                     | Description                                                                                                           |
+| ------------------ | ------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| NODE_ENV           | `undefined`              | <code>'production' &#124; 'test' &#124; undefined</code> | What kind of environment that Logto runs in. If you run Logto via `npm start`, the value will always be `production`. |
+| PORT               | `3001`                   | `number`                                                 | The local port that Logto listens.                                                                                    |
+| DB_URL             | N/A                      | `string`                                                 | The [Postgres DSN](https://www.postgresql.org/docs/14/libpq-connect.html#id-1.7.3.8.3.6) for Logto database.          |
+| HTTPS_CERT_PATH    | `undefined`              | <code>string &#124; undefined</code>                     | See [Enabling HTTPS](#enabling-https) for details.                                                                    |
+| HTTPS_KEY_PATH     | `undefined`              | <code>string &#124; undefined</code>                     | Ditto.                                                                                                                |
+| TRUST_PROXY_HEADER | `false`                  | `boolean`                                                | Ditto.                                                                                                                |
+| ADMIN_RESOURCE     | `'https://api.logto.io'` | `string`                                                 | The resource indicator for Logto management APIs.                                                                     |
+
+### OIDC
+
+| Key                   | Default Value                   | Type                                 | Description                                                                                                                                                                              |
+| --------------------- | ------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OIDC_PRIVATE_KEY      | N/A                             | <code>string &#124; undefined</code> | The content of private key for [OIDC JWT signing](https://openid.net/specs/openid-connect-core-1_0.html#Signing). <br/> If you'd like to set this in `.env`, you can leverage [multiline values](https://github.com/motdotla/dotenv#multiline-values) support.                                                                       |
+| OIDC_PRIVATE_KEY_PATH | `'./oidc-private-key.pem'`      | <code>string &#124; undefined</code> | The path to the private key file for [OIDC JWT signing](https://openid.net/specs/openid-connect-core-1_0.html#Signing). <br/> Note Logto will *ignore* this value if `OIDC_PRIVATE_KEY` is not empty. |
+| OIDC_ISSUER           | `'http://localhost:$PORT/oidc'` | `string`                             | The [issuer identifier](https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier) for OIDC. Usually it's the URL to your OIDC provider.                                                                                                                         |
+
+#### Supported Key Types
+
+- RSA
+- OKP (Ed25519, Ed448, X25519, X448 sub types)
+- EC (P-256, secp256k1, P-384, and P-521 curves)
+
+:::note
+Logto mounts OIDC provider under path `/oidc`. That means if you mount Logto under `https://your.domain.com/logto`, the value of `OIDC_ISSUER` should be `https://your.domain.com/logto/oidc`.
+:::
+
+## Enabling HTTPS
+
+### Using Node
+
+Node natively supports HTTPS. Provide **BOTH** `HTTPS_CERT_PATH` and `HTTPS_KEY_PATH` to enable HTTPS via Node.
+
+`HTTPS_CERT_PATH` implies the path to your HTTPS certificate, while `HTTPS_KEY_PATH` implies the path to your HTTPS key.
+
+### Using a HTTPS Proxy
+
+Another common practice is to have a HTTPS proxy in front of Node. 
+
+In this case, you're likely want to set `TRUST_PROXY_HEADER` to `true` which indicates if proxy header fields should be trusted. Logto will pass the value to [Koa app settings](https://github.com/koajs/koa/blob/master/docs/api/index.md#settings).
+
+See [Trusting TLS offloading proxies](https://github.com/panva/node-oidc-provider/blob/main/docs/README.md#trusting-tls-offloading-proxies) for when to configure this field.