mirror of
https://github.com/logto-io/logto.git
synced 2024-12-16 20:26:19 -05:00
Merge pull request #724 from logto-io/log-2343-log-introduction
docs: init introduction
This commit is contained in:
Gao Sun
GitHub
commit
08aadf9a00
7 changed files with 144 additions and 9 deletions
11
.vscode/settings.json
vendored
11
.vscode/settings.json
vendored
|
|
@ -19,5 +19,14 @@
|
|||
],
|
||||
"editor.codeActionsOnSave": {
|
||||
"source.fixAll.eslint": true,
|
||||
}
|
||||
},
|
||||
"cSpell.words": [
|
||||
"Alipay",
|
||||
"CIAM",
|
||||
"Logto",
|
||||
"oidc",
|
||||
"Passwordless",
|
||||
"silverhand",
|
||||
"slonik"
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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({
|
||||
|
|
|
|||
|
|
@ -19,12 +19,12 @@ const loadEnvValues = async () => {
|
|||
return Object.freeze({
|
||||
isTest,
|
||||
isProduction,
|
||||
isHttpsEnabled: Boolean(process.env.HTTPS_CERT && process.env.HTTPS_KEY),
|
||||
httpsCert: process.env.HTTPS_CERT,
|
||||
httpsKey: process.env.HTTPS_KEY,
|
||||
isHttpsEnabled: Boolean(process.env.HTTPS_CERT_PATH && process.env.HTTPS_KEY_PATH),
|
||||
httpsCert: process.env.HTTPS_CERT_PATH,
|
||||
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),
|
||||
});
|
||||
|
|
|
|||
|
|
@ -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');
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
78
packages/docs/docs/tutorial/configuration.md
Normal file
78
packages/docs/docs/tutorial/configuration.md
Normal file
|
|
@ -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' | 'test' | 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 | undefined</code> | See [Enabling HTTPS](#enabling-https) for details. |
|
||||
| HTTPS_KEY_PATH | `undefined` | <code>string | 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 | 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 | 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.
|
||||
Loading…
Reference in a new issue