Infrastructure/logto
0
Fork 0
mirror of https://github.com/logto-io/logto.git synced 2024-12-16 20:26:19 -05:00
Code Issues Activity

docs: configuration

Browse source
This commit is contained in:
Gao Sun 2022-05-05 22:39:28 +08:00
parent 4400d8d25e
commit 9ca2815452
No known key found for this signature in database
GPG key ID: 13EBE123E4773688
5 changed files with 59 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
packages/core/src/env-set/index.ts
View file

@ -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),
});

2
packages/core/src/env-set/oidc.ts
View file

@ -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');

2
packages/core/src/index.ts
View file

@ -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
packages/docs/docs/tutorial/README.md
View file

@ -38,7 +38,7 @@ In your terminal:
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 text:
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
@ -52,4 +52,4 @@ TBD
### Configuration
Logto uses environment variables for configuration, along with `.env` file support. See [Configuration](./configuration) for detailed usage and full option list.
Logto uses environment variables for configuration, along with `.env` file support. See [Configuration](./configuration) for detailed usage and full variable list.

60
packages/docs/docs/tutorial/configuration.md
View file

@ -6,26 +6,24 @@ sidebar_position: 2
## Usage
Logto handles environment variables with the following order:
Logto handles environment variables in the following order:
- The `.env` file in the project root
- The `.env` file in the project root, which conforms with [dotenv](https://github.com/motdotla/dotenv#readme) format
- System environment variable
Thus if the system environment variable will override the value in `.env`.
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 set of password peppers
- If you'd like to generate a private key for OIDC provider
- 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)
- Finally the domain for Logto
Most of them are just simple yes / no questions or you can use the default value, except 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 OIDC provider will locate on `./oidc-private-key.pem`, while other values will append to `./.env`.
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.
@ -33,4 +31,48 @@ The `--no-inquiry` parameter is appended by default in the Docker image.
## Variable List
TBF in the next PR
### 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.