# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.novel.dev/novel-server/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.