Server configuration#

`/config/server` manages host, port, URL, proxy, cron, and more; changes require rebuilding the admin panel.

The /config/server.js file is used to define the server configuration for a Strapi application.

Changes to the server.js file require rebuilding the admin panel. After saving the modified file run either yarn build or npm run build in the terminal to implement the changes.

Available options#

The /config/server.js file can include the following parameters:

Parameter	Description	Type	Default
`host` ❗️ Mandatory	Host name	string	`localhost`
`port` ❗️ Mandatory	Port on which the server should be running.	integer	`1337`
`app.keys` ❗️ Mandatory	Declare session keys (based on ), which is used by the `session` middleware for the Users & Permissions plugin and the Documentation plugin.	array of strings	`undefined`
`app.proxyIpHeader`	Proxy IP header name to trust when identifying the client's real IP address. Set when behind a reverse proxy (e.g., Nginx, Apache, load balancer). For security, always pair with `app.maxIpsCount` to prevent header spoofing. Example: `'X-Forwarded-For'`, `'CF-Connecting-IP'`.	string	`'X-Forwarded-For'`
`app.maxIpsCount`	Maximum number of IP addresses to read from the proxy IP header. Must be set when using a reverse proxy to prevent IP spoofing attacks. Set to `1` for a single proxy, `2` for proxy chains, etc. Setting to `0` (Koa default) means unlimited, which is insecure behind a proxy.	integer	`0`
`socket`	Listens on a socket. Host and port are cosmetic when this option is provided and likewise use `url` to generate proper urls when using this option. This option is useful for running a server without exposing a port and using proxy servers on the same machine (e.g )	string \| integer	`/tmp/nginx.socket`
`emitErrors`	Enable errors to be emitted to `koa` when they happen in order to attach custom logic or use error reporting services.	boolean	`false`
`url`	Public url of the server. Required for many different features (ex: reset password, third login providers etc.). Also enables proxy support such as Apache or Nginx, example: `https://mywebsite.com/api`. The url can be relative, if so, it is used with `http://${host}:${port}` as the base url. An absolute url is however recommended.	string	`''`
`proxy`	Proxy configuration	object
`proxy.global`	Defines the proxy agent for all external requests. To be used if the Strapi project is behind a forward proxy.	string
`proxy.fetch`	The proxy for all requests made within `strapi.fetch` (used for licenses check, telemetry and webhooks)	string \|
`proxy.http`	The proxy for all (non-fetch) http requests	string
`proxy.https`	The proxy for all (non-fetch) https requests	string
`proxy.koa`	Set the koa variable `app.proxy`. When `true`, proxy header fields will be trusted.	boolean	`false`
`cron`	Cron configuration (powered by )	object
`cron.enabled`	Enable or disable CRON jobs to schedule jobs at specific dates.	boolean	`false`
`cron.tasks`	Declare CRON jobs to be run at specific dates.	object
`dirs`	Path configuration of different directories Strapi uses.	object
`dirs.public`	Customize the path of the public folder.	string	`./public`
`http`	Configuration of the http server used by Strapi	object
`http.serverOptions`	Options passed to http `createServer`		{}
`transfer.remote.enabled`	Toggle the ability to use the transfer feature	boolean	`true`
`transfer.remote.assetIdleTimeoutMs`	Timeout in milliseconds without incoming data before an asset stream is considered stalled when using `strapi transfer --from` to pull from a remote instance. Increase this value when transferring large files or when working on slow connections.	integer
`webhooks.populateRelations`	When `true`, relation fields are included in webhook event payloads. Set to `false` to keep payloads lightweight and avoid exposing relational data in outgoing webhook requests.	boolean	`true`
`logger.startup.enabled`	Toggle the startup message in the terminal	boolean	`true`
`logger.updates.enabled`	Toggle the notification message about updating strapi in the terminal	boolean	`true`
`openapi`	OpenAPI endpoint configuration. Both endpoints use `access: 'disabled'` by default and are not registered.	object
`openapi['content-api'].access`	Access mode: `disabled` (not registered) or `public` (no authentication).	string	`disabled`
`openapi['content-api'].route.path`	Subpath for the Content API endpoint, resolved under the REST API prefix.	string	`/openapi.json`
`openapi['content-api'].cache.enabled`	Enable file-based caching of the generated specification.	boolean	`true`
`openapi['content-api'].cache.maxAgeMs`	Cache validity in milliseconds.	integer	`60000`
`openapi['content-api'].cache.filePath`	File path for the cached specification. Relative paths resolve from the application root.	string	`.strapi/openapi/content-api.json`
`openapi.admin.access`	Access mode: `disabled` (not registered) or `authenticated` (requires admin session).	string	`disabled`
`openapi.admin.route.path`	Subpath for the Admin endpoint, resolved under the admin path.	string	`/openapi.json`
`openapi.admin.cache.enabled`	Enable file-based caching of the generated specification.	boolean	`true`
`openapi.admin.cache.maxAgeMs`	Cache validity in milliseconds.	integer	`60000`
`openapi.admin.cache.filePath`	File path for the cached specification. Relative paths resolve from the application root.	string	`.strapi/openapi/admin.json`

Info

There is no Strapi-specific keep alive configuration option, because Strapi uses Node's default one for incoming HTTP requests, keeping connections alive by default.

For outgoing HTTP calls, you can pass a keep-alive agent to your HTTP client.
Example with agentkeepalive and Axios:

const { HttpsAgent } = require('agentkeepalive');
const axios = require('axios');

const agent = new HttpsAgent();
axios.get('https://example.com', { httpsAgent: agent });

Configurations#

The /config/server.js minimal configuration requires the host and port parameters for development. Additional parameters can be included for a full configuration.

The default configuration created with any new project should at least include the following:

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
});

export default ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
  },
});

The following is an example of a full configuration file. Not all of these keys are required (see available options).

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
    proxyIpHeader: env('PROXY_IP_HEADER', 'X-Forwarded-For'),
    maxIpsCount: env.int('MAX_IPS_COUNT', 1),
  },
  socket: '/tmp/nginx.socket', // only use if absolutely required
  emitErrors: false,
  url: env('PUBLIC_URL', 'https://api.example.com'),
  proxy: { koa: env.bool('IS_PROXIED', true) },
  cron: {
    enabled: env.bool('CRON_ENABLED', false),
  },
  transfer: {
    remote: {
      enabled: false,
    },
  },
  webhooks: {
    populateRelations: false,
  },
  logger: {
    updates: {
      enabled: false,
    },
    startup: {
      enabled: false,
    },
  },
  // highlight-start
  openapi: {
    'content-api': {
      access: 'public',
    },
  },
  // highlight-end
});

export default ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  app: {
    keys: env.array('APP_KEYS'),
    proxyIpHeader: env('PROXY_IP_HEADER', 'X-Forwarded-For'),
    maxIpsCount: env.int('MAX_IPS_COUNT', 1),
  },
  socket: '/tmp/nginx.socket', // only use if absolutely required
  emitErrors: false,
  url: env('PUBLIC_URL', 'https://api.example.com'),
  proxy: { koa: env.bool('IS_PROXIED', true) },
  cron: {
    enabled: env.bool('CRON_ENABLED', false),
  },
  transfer: {
    remote: {
      enabled: false,
    },
  },
  webhooks: {
    populateRelations: false,
  },
  logger: {
    updates: {
      enabled: false,
    },
    startup: {
      enabled: false,
    },
  },
  // highlight-start
  openapi: {
    'content-api': {
      access: 'public',
    },
  },
  // highlight-end
});