> For the complete documentation index, see [llms.txt](https://docs.novel.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.novel.dev/novel-server/configuration.md).

# Configuration

You have access to different configuration that change the behaviour of Novel.

These configuration live in the `/config`directory of your Novel instance. Different files annotate which parts of the app the configuration impacts.

{% hint style="danger" %}
**ATTENTION!**

Do not commit sensitive information like passwords and API keys to your repository.
{% endhint %}

## Usage

You can use configuration from the config directory like below

<pre class="language-typescript" data-title="app/feature.ts" data-line-numbers><code class="lang-typescript"><strong>import config from 'novel/config';
</strong><strong>
</strong>config('app.host');
</code></pre>

Quick guide on how to modify these files are discussed here

{% embed url="<https://docs.novel.dev/guides/knowledge-base/novel-server/configuring-novel>" %}

### `config(path: string, defaultValue: string)`

You can fetch any configuration from the configuration registry using JSON path. The values are available in the Configuration reference below

<pre class="language-typescript" data-title="app/feature.ts" data-line-numbers><code class="lang-typescript"><strong>import config from 'novel/config';
</strong><strong>// Using default value
</strong>config('app.host', 'some-other-host-if-it-doesnt-exist.com');
</code></pre>

### `set(path: string, value: any)`

You can also modify any setting in runtime. **This is not advisable** but you may have a need for it regardless.

<pre class="language-typescript" data-title="app/feature.ts" data-line-numbers><code class="lang-typescript"><strong>import { set } from 'novel/config';
</strong><strong>
</strong>config('custom.setting', 'john@doe.com');
</code></pre>

It is advisable to do this in a place before your app starts preferrably in `/app/index.ts`because in production mode, multiple processes will be spun up, and your setting may not be applied in different processes.

## Environment

{% hint style="info" %}
Environment variables are loaded during startup-time.
{% endhint %}

Your instance will respect the values available in your current terminal context as well as the supplied `.env`file in the project root.

You can refer to the sample file in <https://github.com/madewithnovel/novel/blob/main/.env.sample>

### Minimum Required Environment Variables

<table><thead><tr><th width="288">Environment Variable</th><th>Description</th></tr></thead><tbody><tr><td><code>HOST</code></td><td>The full domain that is used to access the instance</td></tr><tr><td><code>DB_HOST</code></td><td>The connection string used by <code>/config/database.js</code></td></tr><tr><td><code>STRIPE_API_TOKEN</code></td><td>The API token used by Stripe</td></tr><tr><td><code>POSTMARK_API_TOKEN</code></td><td>The API token used by Postmark</td></tr></tbody></table>

{% hint style="danger" %}
**ATTENTION!**

Do not commit sensitive information like passwords and API keys to your repository.
{% endhint %}

{% embed url="<https://docs.novel.dev/guides/knowledge-base/general-information/using-sentry>" %}

## Configuration

{% hint style="info" %}
Configuration is loaded during startup-time.
{% endhint %}

The default configuration that you can reference lives in `/packages/novel/lib/default.js`

The configuration files in the `/config`directory are in `.js`files and not typescript files. They do, however, can be written in esm format. They are not transpiled.

{% hint style="warning" %}
Configuration in these files are not dependent on the environment except if the config values reference environment variables.
{% endhint %}

### App

This file controls application level flags. This file is located in `/config/app.js`

<table data-full-width="false"><thead><tr><th width="175">Key</th><th width="348">Description</th><th>Default Value</th></tr></thead><tbody><tr><td>host</td><td>The hostname that this instance will be run from. In production, it is advisable to use your domain name here</td><td><ul><li>process.env.HOST</li><li>http://localhost:7634</li></ul></td></tr><tr><td>web</td><td>If you are using Novel Web standalone in vercel, you need to modify this to point to the hostname you use in vercel. See <a data-mention href="/pages/8xYJS5bBL2pVnM67IchA">/pages/8xYJS5bBL2pVnM67IchA</a></td><td><ul><li>process.env.WEB_HOST</li><li>process.env.HOST</li><li>http://localhost:7634</li></ul></td></tr><tr><td>secure</td><td>Controls whether the instance should run in https</td><td>false</td></tr><tr><td>cors.origin</td><td>Controls where requests can come from, this can be an array or a boolean, or a string of the domain that is trying to access Novel API. See <a href="https://github.com/fastify/fastify-cors">https://github.com/fastify/fastify-cors</a> for more information</td><td>true</td></tr><tr><td>session.lifetime</td><td>Controls how long the session lasts for logged in users</td><td>1h</td></tr><tr><td>socket</td><td>Controls whether sockets are enabled in the instance. See <a data-mention href="/pages/8NeTFbbhUZFuSX47A7f9">/pages/8NeTFbbhUZFuSX47A7f9</a> for more information</td><td>false</td></tr><tr><td>notify_webhook</td><td>Used internally if you would like various internal events to be emitted to the destination of your choice. Accepts slack or discord endpoints for now.</td><td>process.env.NOTIFY_WEBHOOK</td></tr><tr><td>devtools</td><td>Enables Novel devtool inspection </td><td>true</td></tr><tr><td>telemetry</td><td>Enables telemetry collection of transactions/errors within the packages/novel directory. Used for product improvements. </td><td>true</td></tr></tbody></table>

### Database

This file controls database settings. This file is located in `/config/database.js`

<table data-full-width="false"><thead><tr><th width="175">Key</th><th width="348">Description</th><th>Default Value</th></tr></thead><tbody><tr><td>connection</td><td>Connection string of the PostgreSQL database.</td><td>process.env.DB_HOST</td></tr><tr><td>cloudsql.enabled</td><td>Experimental. Enable CloudSQL endpoints</td><td>false</td></tr><tr><td>cloudsql.tables</td><td>Experimental. The tables that are allowed to be exposed by CloudSQL.</td><td>[]</td></tr></tbody></table>

### Auth

This file controls authentication related settings. This file is located in `/config/auth.js`

<table data-full-width="false"><thead><tr><th width="219">Key</th><th width="355">Description</th><th>Default Value</th></tr></thead><tbody><tr><td>mfa</td><td>Enable the use of MFA</td><td>true</td></tr><tr><td>register_on_oauth</td><td>Register the account if it doesnt exist if coming from an Oauth flow</td><td>false</td></tr><tr><td>allow_unverified</td><td>Allow accounts to access the app even if they are unverified</td><td>false</td></tr><tr><td>verification_expiry</td><td>The time the verification link is available.</td><td>3d</td></tr><tr><td>routes.login</td><td>The URL in the front end for use in redirects</td><td>/login</td></tr><tr><td>routes.mfa</td><td>The URL in the front end for use in redirects</td><td>/login/mfa</td></tr><tr><td>routes.link</td><td>The URL in the front end for use in redirects</td><td>/login/link</td></tr><tr><td>routes.forget</td><td>The URL in the front end for use in redirects</td><td>/login/forget</td></tr><tr><td>routes.verify</td><td>The URL in the front end for use in redirects</td><td>/mail/verify</td></tr><tr><td>routes.signup</td><td>The URL in the front end for use in redirects</td><td>/signup</td></tr><tr><td>routes.after_login</td><td>The URL in the front end for use in redirects</td><td>/dashboard</td></tr><tr><td>routes.logout</td><td>The URL in the front end for use in redirects</td><td>/logout</td></tr><tr><td>roles</td><td>Roles available in the app. See <a data-mention href="/pages/YnCI9EvKEucRMliY1P0r">/pages/YnCI9EvKEucRMliY1P0r</a></td><td></td></tr></tbody></table>

### Mail

This file controls mail delivery. This file is located in `/config/mail.js`

{% embed url="<https://docs.novel.dev/guides/knowledge-base/novel-server/email-providers>" %}

{% embed url="<https://docs.novel.dev/guides/knowledge-base/general-information/getting-postmark-keys>" %}

<table data-full-width="false"><thead><tr><th width="175">Key</th><th width="348">Description</th><th>Default Value</th></tr></thead><tbody><tr><td>driver</td><td>Driver used for sending mail. smtp or postmark</td><td>postmark</td></tr><tr><td>credentials.token</td><td>The token used by postmark</td><td>process.env.POSTMARK_SERVER_TOKEN</td></tr><tr><td>credentials.host</td><td>The connection string of your SMTP server</td><td>process.env.SMTP_HOST</td></tr><tr><td>defaults.from</td><td>Default from address and name to sign off your emails</td><td>process.env.DEFAULT_MAIL_FROM</td></tr></tbody></table>

### SaaS

This file controls how your SaaS behaves. This file is located in `/config/saas.js`

{% embed url="<https://docs.novel.dev/guides/knowledge-base/general-information/getting-stripe-keys>" %}

<table data-full-width="false"><thead><tr><th width="201">Key</th><th width="348">Description</th><th>Default Value</th></tr></thead><tbody><tr><td>driver</td><td>Driver used to manage your SaaS</td><td>stripe</td></tr><tr><td>credentials.token</td><td>The API token used by Stripe</td><td>process.env.STRIPE_API_TOKEN</td></tr><tr><td>credentials.webhook</td><td>The secret used by Stripe to validate the webhook payload</td><td>process.env.STRIPE_WEBHOOK_SECRET</td></tr><tr><td>sync</td><td>Recommended. If changes in the plans config are applied to Stripe automatically</td><td>true</td></tr><tr><td>archive_on_remote</td><td>If the plans are removed in the plans config, remove them in Stripe as well</td><td>true</td></tr><tr><td>tax_included</td><td>If tax is included for any automatically generated products/prices</td><td>false</td></tr><tr><td>currencies</td><td>Available currencies you support</td><td>['USD']</td></tr><tr><td>aggregate_usage</td><td>If usage based billing is used. See <a href="https://stripe.com/billing/usage-based-billing">Usage Based BIlling</a></td><td>sum</td></tr><tr><td>upfront</td><td>Enable if upfront collection is required for subscriptions to be created.</td><td>false</td></tr><tr><td>plans</td><td>See Plans below</td><td>[]</td></tr></tbody></table>

#### Plans

{% code title="config/saas.js" lineNumbers="true" %}

```typescript
{
    // Unique ID for the plan
    id: 'standard-2024',
    
    // A human-readable name for the plan
    name: 'Standard',
    
    // Show this plan on the plans endpoint
    frontpage: true,
    
    // The monthly price for the plan
    monthly: [29],
    
    // The yearly price for the plan
    yearly: [290],
    
    // If the plan supports a trial period
    trial: 30,
    
    // The meter used for usage based billing
    meter: null,
    
    // Flags that are enabled to users/orgs that have this plan
    flags: ['projects'],
    
    // Limits applied to the users/orgs that have this plan
    limits: {
        projects: 5,
        seats: 2,
    },
}
```

{% endcode %}

See <https://github.com/madewithnovel/novel/blob/main/config/saas.js>

{% embed url="<https://docs.novel.dev/guides/knowledge-base/novel-server/configuring-pricing>" %}

### Filesystem

This file controls how files are handled during uploads and management. This file is located in `/config/filesystem.js`

<table data-full-width="false"><thead><tr><th width="175">Key</th><th width="348">Description</th><th>Default Value</th></tr></thead><tbody><tr><td>driver</td><td>Driver to use for file management</td><td>s3</td></tr><tr><td>public_url</td><td>The URL assets use to generate their public URLs</td><td>process.env.FILESYSTEM_PUBLIC_URL</td></tr><tr><td>default_bucket</td><td>A bucket that files belong to. To comply with S3 schemes.</td><td><ul><li>process.env.FILESYSTEM_DEFAULT_BUCKET</li><li>default</li></ul></td></tr><tr><td>credentials.endpoint</td><td>URL where uploads can be sent to</td><td>process.env.FILESYSTEM_ENDPOINT</td></tr><tr><td>credentials.client_id</td><td>Credentials of the remote file system</td><td>process.env.FILESYSTEM_ACCESS_KEY_ID</td></tr><tr><td>credentials.secret_key</td><td>Credentials of the remote file system</td><td>process.env.FILESYSTEM_SECRET_ACCESS_KEY</td></tr><tr><td>types</td><td>Types supported by the upload. See <a href="https://www.npmjs.com/package/mime">https://www.npmjs.com/package/mime</a></td><td>['image', 'audio', 'video', 'application/pdf', 'application/vnd.', 'text']</td></tr></tbody></table>

{% embed url="<https://docs.novel.dev/guides/knowledge-base/general-information/using-aws-s3>" %}

{% embed url="<https://docs.novel.dev/guides/knowledge-base/general-information/using-cloudflare-r2>" %}

{% hint style="danger" %}
**ATTENTION!**

Do not commit sensitive information like passwords and API keys to your repository.
{% endhint %}

## Changelog

* 2024-12-20 - Initial Documentation