Server configuration

Configure Silex server behavior with environment variables and config plugins.

Overview

The Silex server loads configuration from two sources:

1. Environment variables — Set before startup, control ports, URLs, connectors, and limits
2. Config file — A JavaScript/TypeScript plugin that customizes connectors, adds routes, and hooks into server events

The config file is treated as a plugin: it receives a ServerConfig object and can add connectors, listen to events, and extend the Express server.

Prerequisites

• Running Silex server (Docker, Node, or self-hosted)
• Basic Node.js and JavaScript knowledge for config files
• Understanding of storage and hosting connectors

Environment variables

All environment variables are optional except SILEX_SESSION_SECRET (recommended for security).

Core server settings

Variable	Default	Purpose
SILEX_PORT	6805	Port the server listens on
SILEX_HOST	localhost	Hostname (0.0.0.0 for remote access)
SILEX_PROTOCOL	http	http or https (before reverse proxy)
SILEX_URL	${PROTOCOL}://${HOST}:${PORT}	Public URL users visit
SILEX_DEBUG	false	Set to true for verbose logs and config reloading
SILEX_SESSION_NAME	silex-session	Session cookie name
SILEX_SESSION_SECRET	(none)	Random key for session encryption; min 32 chars

Express request limits

For large file uploads or data:

Variable	Default	Purpose
SILEX_EXPRESS_JSON_LIMIT	100kb	Max JSON body size
SILEX_EXPRESS_TEXT_LIMIT	1mb	Max text body size
SILEX_EXPRESS_URLENCODED_LIMIT	100kb	Max form-encoded body size

SSL/HTTPS

For HTTPS without a reverse proxy:

Variable	Default	Purpose
SILEX_SSL_PORT	(none)	HTTPS port (e.g., 443)
SILEX_SSL_PRIVATE_KEY	(none)	Path to private key file
SILEX_SSL_CERTIFICATE	(none)	Path to certificate file
SILEX_FORCE_HTTPS	false	Redirect HTTP to HTTPS
SILEX_FORCE_HTTPS_TRUST_XFP_HEADER	false	Trust X-Forwarded-Proto header from reverse proxy

CORS and client config

Variable	Default	Purpose
SILEX_CORS_URL	(none)	Allow requests from this origin (e.g., https://editor.example.com)
SILEX_CLIENT_CONFIG	(none)	Path to client config file (served at /client-config.js)

Connectors

Variable	Default	Purpose
STORAGE_CONNECTORS	fs	Comma-separated list: fs, gitlab, ftp
HOSTING_CONNECTORS	fs,download	Comma-separated list: fs, gitlab, ftp, download
SILEX_FS_ROOT	/silex/storage	Filesystem storage path
SILEX_FS_HOSTING_ROOT	/silex/hosting	Filesystem hosting path
FTP_STORAGE_PATH	(none)	Root path on FTP server for storage
FTP_HOSTING_PATH	(none)	Root path on FTP server for hosting
GITLAB_DISPLAY_NAME	(none)	Display name for the primary GitLab connector
GITLAB_DOMAIN	(none)	GitLab instance domain (e.g., gitlab.com)
GITLAB_CLIENT_ID	(none)	OAuth application ID for GitLab
GITLAB_CLIENT_SECRET	(none)	OAuth application secret for GitLab
GITLAB2_DISPLAY_NAME	(none)	Display name for a second GitLab connector
GITLAB2_DOMAIN	(none)	Domain for the second GitLab instance
GITLAB2_CLIENT_ID	(none)	OAuth application ID for second GitLab
GITLAB2_CLIENT_SECRET	(none)	OAuth application secret for second GitLab

NocoDB integration

Variable	Default	Purpose
NOCO_URL	(none)	NocoDB instance URL
NOCO_API_KEY	(none)	NocoDB API key
NOCO_TABLE	(none)	NocoDB table name for website metadata

Config file paths

Variable	Default	Purpose
SILEX_SERVER_CONFIG	.silex.js	Path to server config file (relative to cwd)

Config file (plugin pattern)

The config file is a module that exports an async function receiving ServerConfig. Here's a minimal example:

// .silex.js
module.exports = async function (config) {
  console.log('Silex server is starting')
  // Add plugins, connectors, routes, listeners here
}

ServerConfig API

class ServerConfig extends Config {
  // Core properties
  port: string | undefined
  debug: boolean
  url: string
  userConfigPath: Plugin | undefined
  configFilePath: Plugin

  // Connectors
  addStorageConnector(connector: StorageConnector | StorageConnector[]): void
  setStorageConnectors(connectors: StorageConnector[]): void
  getStorageConnectors(): StorageConnector[]
  addHostingConnector(connector: HostingConnector | HostingConnector[]): void
  setHostingConnectors(connectors: HostingConnector[]): void
  getHostingConnectors(): HostingConnector[]
  getConnectors(type?: ConnectorType | string | null): Connector[]

  // Plugins
  async addPlugin(plugin: Plugin, options: any): Promise<void>

  // Routes
  async addRoutes(app: Express.Application): Promise<void>

  // Events
  on(event: ServerEvent, listener: Function): void
  off(event: ServerEvent, listener: Function): void
  emit(event: ServerEvent, data?: any): void
}

Adding connectors in config

Example: Enable GitLab and FTP storage connectors:

const GitlabConnector = require('@silexlabs/silex-plugins').GitlabConnector
const FtpConnector = require('@silexlabs/silex-plugins').FtpConnector

module.exports = async function (config) {
  // Clear default filesystem connector
  config.setStorageConnectors([])

  // Add GitLab storage
  config.addStorageConnector(
    new GitlabConnector(config, {
      clientId: process.env.GITLAB_CLIENT_ID,
      clientSecret: process.env.GITLAB_CLIENT_SECRET,
      domain: process.env.GITLAB_DOMAIN,
    })
  )

  // Add FTP storage
  config.addStorageConnector(
    new FtpConnector(config, {
      type: 'storage',
      path: process.env.FTP_STORAGE_PATH,
    })
  )
}

Adding routes

Extend the Express server with custom routes:

module.exports = async function (config) {
  // This is called after the Express app is set up
  // but before plugins are loaded
  const originalAddRoutes = config.addRoutes.bind(config)
  config.addRoutes = async (app) => {
    await originalAddRoutes(app)

    // Add a custom endpoint
    app.get('/api/custom', (req, res) => {
      res.json({ message: 'Custom route' })
    })

    // Add a static file route
    app.use('/my-files', express.static('/path/to/files'))
  }
}

Listening to server events

The config object is an event emitter. Listen to lifecycle events:

const { ServerEvent } = require('@silexlabs/silex/dist/server/events')

module.exports = async function (config) {
  config.on(ServerEvent.STARTUP_START, () => {
    console.log('Server is starting')
  })

  config.on(ServerEvent.STARTUP_END, () => {
    console.log('Server is ready')
  })

  config.on(ServerEvent.PUBLISH_START, async (publicationData) => {
    console.log(`Publishing website: ${publicationData.siteSettings.name}`)
  })

  config.on(ServerEvent.PUBLISH_END, async (error) => {
    if (error) {
      console.error(`Publication failed: ${error.message}`)
    } else {
      console.log('Publication successful')
    }
  })

  config.on(ServerEvent.WEBSITE_STORE_START, async ({ websiteId, connectorId }) => {
    console.log(`Saving website ${websiteId} to connector ${connectorId}`)
  })
}

Server events

Event	Type	Purpose
STARTUP_START	none	Server is initializing
STARTUP_END	none	Server is ready to accept requests
PUBLISH_START	PublicationData	Publication begins
PUBLISH_END	Error | null	Publication complete (error if failed)
WEBSITE_STORE_START	{websiteId, websiteData, connectorId}	About to save website
WEBSITE_STORE_END	Error | null	Website saved
WEBSITE_ASSET_STORE_START	{files, websiteId, connectorId}	About to save assets
WEBSITE_ASSET_STORE_END	Error | null	Assets saved

Using plugins in config

Load additional plugins by calling config.addPlugin():

const dashPlugin = require('@silexlabs/silex-dashboard')
const customPlugin = require('./my-plugin.js')

module.exports = async function (config) {
  // Load dashboard plugin
  await config.addPlugin(dashPlugin, {})

  // Load custom plugin with options
  await config.addPlugin(customPlugin, {
    option1: 'value1',
    option2: true,
  })
}

Config file location

Silex looks for .silex.js in the working directory by default. Override with:

SILEX_SERVER_CONFIG=/path/to/config.js npm start

The path is relative to the current working directory.

Example: Complete server config

// .silex.js
const path = require('path')
const { ServerEvent } = require('@silexlabs/silex/dist/server/events')
const GitlabConnector = require('@silexlabs/silex-plugins').GitlabConnector
const FtpConnector = require('@silexlabs/silex-plugins').FtpConnector
const FsStorage = require('@silexlabs/silex/dist/server/connectors/FsStorage').FsStorage
const FsHosting = require('@silexlabs/silex/dist/server/connectors/FsHosting').FsHosting

require('dotenv').config()

module.exports = async function (config) {
  console.log(`Starting Silex at ${config.url}`)

  // Set storage connectors
  config.setStorageConnectors([
    new FsStorage(config, {
      path: process.env.SILEX_FS_ROOT || './silex/storage',
    }),
  ])

  // Add optional GitLab storage if credentials are set
  if (process.env.GITLAB_CLIENT_ID) {
    config.addStorageConnector(
      new GitlabConnector(config, {
        clientId: process.env.GITLAB_CLIENT_ID,
        clientSecret: process.env.GITLAB_CLIENT_SECRET,
        domain: process.env.GITLAB_DOMAIN || 'gitlab.com',
      })
    )
  }

  // Set hosting connectors
  config.setHostingConnectors([
    new FsHosting(config, {
      path: process.env.SILEX_FS_HOSTING_ROOT || './silex/hosting',
    }),
  ])

  // Listen to events
  config.on(ServerEvent.PUBLISH_END, (error) => {
    if (error) {
      console.error(`Publication failed: ${error.message}`)
    } else {
      console.log('Website published successfully')
    }
  })
}

Troubleshooting

Config file not found

Ensure .silex.js is in your working directory:

ls -la .silex.js

Or specify the path explicitly:

SILEX_SERVER_CONFIG=./config/silex-config.js npm start

Syntax errors in config file

Enable debug mode to see detailed errors:

SILEX_DEBUG=true npm start

Check the console output for the specific line causing the error.

Connectors not loading

Verify environment variables are set:

env | grep GITLAB
env | grep FTP

Check that the required npm packages are installed:

npm ls @silexlabs/silex-plugins

See also

• Client-side plugin API
• Storage connector setup
• Hosting connector setup
• How CMS works — CMS concepts